@voxgig/sdkgen 4.4.0 → 4.5.0

package/project/.sdk/tm/py/test/test_feature.py

@@ -105,6 +105,10 @@ class TestNetsimFeature:
 @pytest.mark.skipif(not has_feature("retry"), reason="retry not in this SDK")
 class TestRetryFeature:
 
+    # Drives netsim as the simulated network: runnable only when this
+    # SDK was generated with it (the harness skips absent features).
+    @pytest.mark.skipif(not has_feature("netsim"),
+                        reason="netsim not in this SDK")
     def test_retries_transient_failures_then_succeeds(self):
         clock = make_clock()
         h = make_client([
@@ -115,6 +119,10 @@ class TestRetryFeature:
         assert h.op(op="load")["ok"] is True
         assert h.client._retry["attempts"] == 2
 
+    # Drives netsim as the simulated network: runnable only when this
+    # SDK was generated with it (the harness skips absent features).
+    @pytest.mark.skipif(not has_feature("netsim"),
+                        reason="netsim not in this SDK")
     def test_gives_up_after_the_budget(self):
         clock = make_clock()
         h = make_client([
@@ -163,6 +171,10 @@ class TestRetryFeature:
         assert h.op(op="load")["ok"] is True
         assert state["n"] == 2
 
+    # Drives netsim as the simulated network: runnable only when this
+    # SDK was generated with it (the harness skips absent features).
+    @pytest.mark.skipif(not has_feature("netsim"),
+                        reason="netsim not in this SDK")
     def test_honours_a_server_retry_after(self):
         clock = make_clock()
         h = make_client([
@@ -174,6 +186,10 @@ class TestRetryFeature:
         assert h.op(op="load")["ok"] is True
         assert clock.time == 2000
 
+    # Drives netsim as the simulated network: runnable only when this
+    # SDK was generated with it (the harness skips absent features).
+    @pytest.mark.skipif(not has_feature("netsim"),
+                        reason="netsim not in this SDK")
     def test_default_jitter_path_still_succeeds(self):
         h = make_client([
             {"name": "netsim", "options": {"failTimes": 1}},
@@ -202,6 +218,10 @@ class TestRetryFeature:
 @pytest.mark.skipif(not has_feature("timeout"), reason="timeout not in this SDK")
 class TestTimeoutFeature:
 
+    # Drives netsim as the simulated network: runnable only when this
+    # SDK was generated with it (the harness skips absent features).
+    @pytest.mark.skipif(not has_feature("netsim"),
+                        reason="netsim not in this SDK")
     def test_a_slow_request_times_out(self):
         clock = make_clock()
         h = make_client([
@@ -438,6 +458,10 @@ class TestRbacFeature:
 @pytest.mark.skipif(not has_feature("metrics"), reason="metrics not in this SDK")
 class TestMetricsFeature:
 
+    # Drives netsim as the simulated network: runnable only when this
+    # SDK was generated with it (the harness skips absent features).
+    @pytest.mark.skipif(not has_feature("netsim"),
+                        reason="netsim not in this SDK")
     def test_counts_ok_and_err_per_op(self):
         h = make_client([
             {"name": "netsim", "options": {"failTimes": 1, "failStatus": 500}},
@@ -490,6 +514,10 @@ class TestTelemetryFeature:
         assert sent["X-Trace-Id"] == h.client._telemetry["spans"][0]["traceId"]
         assert re.match(r"^00-.+-.+-01$", sent["traceparent"])
 
+    # Drives netsim as the simulated network: runnable only when this
+    # SDK was generated with it (the harness skips absent features).
+    @pytest.mark.skipif(not has_feature("netsim"),
+                        reason="netsim not in this SDK")
     def test_records_a_failed_span_on_error(self):
         h = make_client([
             {"name": "netsim", "options": {"failTimes": 1, "failStatus": 500}},
@@ -498,6 +526,10 @@ class TestTelemetryFeature:
         h.op(op="load")
         assert h.client._telemetry["spans"][0]["ok"] is False
 
+    # Drives netsim as the simulated network: runnable only when this
+    # SDK was generated with it (the harness skips absent features).
+    @pytest.mark.skipif(not has_feature("netsim"),
+                        reason="netsim not in this SDK")
     def test_closes_each_span_exactly_once(self):
         h = make_client([
             {"name": "netsim", "options": {"failTimes": 1, "failStatus": 500}},
@@ -542,6 +574,10 @@ class TestDebugFeature:
         assert len(seen) == 2
         assert seen[0]["headers"]["authorization"] == "<redacted>"
 
+    # Drives netsim as the simulated network: runnable only when this
+    # SDK was generated with it (the harness skips absent features).
+    @pytest.mark.skipif(not has_feature("netsim"),
+                        reason="netsim not in this SDK")
     def test_captures_failures(self):
         h = make_client([
             {"name": "netsim", "options": {"failTimes": 1, "failStatus": 500}},
@@ -571,6 +607,10 @@ class TestDebugFeature:
 @pytest.mark.skipif(not has_feature("audit"), reason="audit not in this SDK")
 class TestAuditFeature:
 
+    # Drives netsim as the simulated network: runnable only when this
+    # SDK was generated with it (the harness skips absent features).
+    @pytest.mark.skipif(not has_feature("netsim"),
+                        reason="netsim not in this SDK")
     def test_one_record_per_op_with_sink_and_actor(self):
         sink = []
         h = make_client([

package/project/.sdk/tm/py/test/test_feature_corpus.py

@@ -23,9 +23,20 @@ from projectname_sdk import ProjectNameSDK
 
 _TEST_DIR = os.path.dirname(os.path.abspath(__file__))
 
-# Features with a corpus section. A name here with no section is a skip, not
-# a failure: an SDK generated without the feature has nothing to run.
-FEATURE_CORPUS_NAMES = ["cost"]
+# Features with a corpus section — read from the corpus itself, so a
+# project-authored section (a custom feature added under
+# .sdk/test/feature/) runs without editing this file. Read eagerly:
+# parametrize needs the names at collection time. An SDK generated
+# without a listed feature still skips, not fails.
+def _corpus_feature_names():
+    try:
+        with open(os.path.join(_TEST_DIR, "../../.sdk/test/test.json"), "r") as f:
+            return sorted((json.loads(f.read()).get("feature") or {}).keys())
+    except OSError:
+        return []
+
+
+FEATURE_CORPUS_NAMES = _corpus_feature_names()
 
 # The standard operation names, in the order the runner prefers them.
 FEATURE_CORPUS_OPS = ["load", "list", "create", "update", "remove"]
@@ -129,6 +140,12 @@ def _candidates(client):
                     "accessor": accessor,
                     "op": opname,
                 })
+
+    # SAFE OPS FIRST - see the ts harness for the reasoning: the cache stores
+    # only successful GETs, so an SDK whose first usable op is a `create`
+    # (POST) can never satisfy "a hit served from cache costs nothing".
+    safe = {"list": 0, "load": 1}
+    out.sort(key=lambda o: (safe.get(o["op"], 2), o["key"]))
     return out
 
 

package/project/.sdk/tm/rb/test/feature_corpus_test.rb

@@ -19,9 +19,10 @@ require_relative "../ProjectName_sdk"
 
 class FeatureCorpusTest < Minitest::Test
 
-  # Features with a corpus section. A name here with no section is a skip,
-  # not a failure: an SDK generated without the feature has nothing to run.
-  FEATURE_CORPUS_NAMES = ["cost"].freeze
+  # Features with a corpus section are read from the corpus itself (see
+  # test_feature_corpus), so a project-authored section - a custom feature
+  # added under .sdk/test/feature/ - runs without editing this file. An SDK
+  # generated without a listed feature still skips, not fails.
 
   # The standard operation names, in the order the runner prefers them.
   FEATURE_CORPUS_OPS = %w[load list create update remove].freeze
@@ -108,7 +109,12 @@ class FeatureCorpusTest < Minitest::Test
         out << { "key" => "#{entname}.#{opname}", "accessor" => accessor, "op" => opname }
       end
     end
-    out
+
+    # SAFE OPS FIRST - see the ts harness for the reasoning: the cache stores
+    # only successful GETs, so an SDK whose first usable op is a `create`
+    # (POST) can never satisfy "a hit served from cache costs nothing".
+    safe = { "list" => 0, "load" => 1 }
+    out.sort_by { |o| [safe.fetch(o["op"], 2), o["key"]] }
   end
 
   def invoke(client, op, ctrl)
@@ -187,6 +193,13 @@ class FeatureCorpusTest < Minitest::Test
   end
 
   def record(client, name)
+    # A corpus key is any manifest item name, so it may carry characters
+    # (foo-bar, foo.2) that cannot form a Ruby instance-variable name. The
+    # probe uses this lookup to SKIP such a section, so answer nil rather
+    # than letting instance_variable_get raise NameError for a feature this
+    # SDK could never have stored under that name anyway.
+    return nil unless name.match?(/\A[A-Za-z0-9_]+\z/)
+
     client.instance_variable_get(:"@_#{name}")
   end
 
@@ -213,7 +226,7 @@ class FeatureCorpusTest < Minitest::Test
   end
 
   def test_feature_corpus
-    FEATURE_CORPUS_NAMES.each do |name|
+    (corpus["feature"] || {}).keys.sort.each do |name|
       section = (corpus["feature"] || {})[name]
       next if section.nil?
 

package/project/.sdk/tm/rust/feature/cost.rs

@@ -41,7 +41,10 @@ pub struct CostBucket {
     pub amount: f64,
 }
 
-#[derive(Default)]
+// NOT `#[derive(Default)]`: the struct holds a `Value`, and `Value` has no
+// `Default` impl — deriving it does not compile. This file only ships when the
+// cost feature is active, so no SDK had ever built it. `Value::Noval` is the
+// absent value, which is what a fresh track should carry.
 pub struct CostTrack {
     // Aggregates (mirrors the ts client._cost record).
     pub currency: String,
@@ -60,6 +63,27 @@ pub struct CostTrack {
     pub seq: i64,
 }
 
+impl Default for CostTrack {
+    fn default() -> Self {
+        CostTrack {
+            currency: String::new(),
+            calls: 0,
+            attempts: 0,
+            amount: 0.0,
+            reported: 0.0,
+            estimated: 0.0,
+            ops: HashMap::new(),
+            actors: HashMap::new(),
+            limit: 0.0,
+            spent: 0.0,
+            remaining: 0.0,
+            exceeded: false,
+            last: Value::Noval,
+            seq: 0,
+        }
+    }
+}
+
 pub struct CostFeature {
     pub name: String,
     pub active: bool,

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

@@ -43,6 +43,13 @@ function ownIdField(config: any, getpath: any, entityName: string): string {
     // key, so move on to the next op rather than guess from it.
     const lastPart = 0 < parts.length ? String(parts[parts.length - 1]) : ''
     if (lastPart.startsWith('{')) return lastPart.slice(1, -1)
+
+    // No path param at all (or the route ends in a literal, e.g.
+    // /orgs/{org}/private-registries/public-key): a single required QUERY
+    // param can still be the record's own key (e.g. GET /result?trace_id=).
+    const query = (best && best.args && best.args.query) || []
+    const reqdQuery = query.filter((q: any) => false !== q.reqd)
+    if (1 === reqdQuery.length) return String(reqdQuery[0].name)
   }
   return 'id'
 }
@@ -332,10 +339,17 @@ class TestFeature extends BaseFeature {
       }
     }
 
-    const reqd = transform(
+    // 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.
+    const reqdParams = transform(
       select(getpath(point, ['args', 'params']), { reqd: true }),
       ['`$EACH`', '', '`$KEY.name`']
     )
+    const reqdQuery = transform(
+      select(getpath(point, ['args', 'query']), { reqd: true }),
+      ['`$EACH`', '', '`$KEY.name`']
+    )
+    const reqd = [...(reqdParams || []), ...(reqdQuery || [])]
 
     const qand: any[] = []
     const q = { '`$AND`': qand }

package/project/.sdk/tm/ts/src/utility/MakeOptionsUtility.ts

@@ -44,11 +44,13 @@ function makeOptions(ctx: Context) {
   // Standard SDK option values.
   const optspec = {
     apikey: '',
+    secret: '',
     base: 'http://localhost:8000',
     prefix: '',
     suffix: '',
     auth: {
-      prefix: ''
+      prefix: '',
+      basic: false
     },
     headers: {
       '`$CHILD`': '`$STRING`'

package/project/.sdk/tm/ts/src/utility/PrepareAuthUtility.ts

@@ -5,6 +5,7 @@ import { Context, Spec } from '../types'
 const HEADER_auth = 'authorization'
 
 const OPTION_apikey = 'apikey'
+const OPTION_secret = 'secret'
 
 const NOTFOUND = '__NOTFOUND__'
 
@@ -40,6 +41,25 @@ function prepareAuth(ctx: Context): Spec | Error {
 
   const apikey = getprop(options, OPTION_apikey, NOTFOUND)
 
+  // True HTTP Basic Auth needs TWO credentials, base64-joined - a single
+  // token in the header (the branch below) can never authenticate against
+  // an API that actually checks `Authorization: Basic base64(user:pass)`.
+  if (true === options.auth.basic) {
+    const secret = getprop(options, OPTION_secret, NOTFOUND)
+    const noApikey = NOTFOUND === apikey || null == apikey || '' === apikey
+    const noSecret = NOTFOUND === secret || null == secret || '' === secret
+
+    if (noApikey || noSecret) {
+      delprop(headers, HEADER_auth)
+    }
+    else {
+      const b64 = Buffer.from(apikey + ':' + secret).toString('base64')
+      setprop(headers, HEADER_auth, prefix ? prefix + ' ' + b64 : b64)
+    }
+
+    return spec
+  }
+
   if (NOTFOUND === apikey || null == apikey || '' === apikey) {
     delprop(headers, HEADER_auth)
   }

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

@@ -25,9 +25,19 @@ import { join } from 'node:path'
 import { SDK, TEST_JSON_FILE } from '../utility/index'
 
 
-// Features with a corpus section. A name here with no section is a skip, not
-// a failure: an SDK generated without the feature has nothing to run.
-const FEATURES = ['cost']
+// Features with a corpus section — read from the corpus itself, so a
+// project-authored section (a custom feature added under
+// .sdk/test/feature/) runs without editing this file. Read eagerly: the
+// node test runner collects the per-feature tests at describe time,
+// before any `before` hook fires. An SDK generated without a listed
+// feature still skips, not fails.
+const FEATURES = Object.keys((() => {
+  try {
+    return JSON.parse(readFileSync(
+      join(__dirname, '..', TEST_JSON_FILE), 'utf8')).feature || {}
+  }
+  catch (e) { return {} }
+})()).sort()
 
 
 // One operation this SDK can actually perform.
@@ -111,7 +121,18 @@ function candidates(client: any): OpRef[] {
       out.push({ key: entity + '.' + op, accessor: accessor[entity], entity, op })
     }
   }
-  return out
+
+  // SAFE OPS FIRST. The corpus calls #OP1 repeatedly and reasons about what
+  // the transport did in between — a cache hit, a retry, a rate-limit wait.
+  // `load`/`list` are the GET ops, and the cache stores only successful GETs,
+  // so an SDK whose first usable op is a `create` (POST) can never satisfy
+  // "a hit served from cache costs nothing": nothing is ever cached, the
+  // second call goes to the network, and cost correctly charges twice. That
+  // reads as a cost defect and is not one. Ordering here rather than
+  // filtering keeps every SDK runnable, including ones with no GET at all.
+  const SAFE: Record<string, number> = { list: 0, load: 1 }
+  return out.sort((a, b) =>
+    (SAFE[a.op] ?? 2) - (SAFE[b.op] ?? 2) || a.key.localeCompare(b.key))
 }
 
 

package/project/.sdk/tm/ts/test/feature.test.ts

@@ -21,6 +21,16 @@ function recordingServer(reply?: (n: number, fetchdef: any) => any) {
 }
 
 
+// A subtest that drives a second feature (netsim as the simulated network)
+// can only run when this SDK was generated with it: the harness skips
+// absent features, which would leave the scenario unsimulated and the
+// assertions meaningless. Same convention as the other targets.
+function skipWithout(name: string): string | boolean {
+  return hasFeature(name) ? false
+    : ('this SDK was generated without the ' + name + ' feature')
+}
+
+
 describe('feature', () => {
 
   test('at least the test feature is present', () => {
@@ -95,7 +105,7 @@ describe('feature', () => {
   // --- retry ----------------------------------------------------------------
   if (hasFeature('retry')) describe('retry', () => {
 
-    test('retries transient failures then succeeds', async () => {
+    test('retries transient failures then succeeds', { skip: skipWithout('netsim') }, async () => {
       const clock = makeClock()
       const h = makeClient({ features: [
         { name: 'netsim', options: { failTimes: 2, failStatus: 503 } },
@@ -105,7 +115,7 @@ describe('feature', () => {
       strictEqual(h.client._retry.attempts, 2)
     })
 
-    test('gives up after the budget', async () => {
+    test('gives up after the budget', { skip: skipWithout('netsim') }, async () => {
       const clock = makeClock()
       const h = makeClient({ features: [
         { name: 'netsim', options: { failTimes: 9, failStatus: 500 } },
@@ -131,7 +141,7 @@ describe('feature', () => {
       strictEqual(n, 3)
     })
 
-    test('honours a server Retry-After', async () => {
+    test('honours a server Retry-After', { skip: skipWithout('netsim') }, async () => {
       const clock = makeClock()
       const h = makeClient({ features: [
         { name: 'netsim', options: { rateLimitTimes: 1, retryAfter: 2 } },
@@ -141,7 +151,7 @@ describe('feature', () => {
       strictEqual(clock.time, 2000)
     })
 
-    test('default jitter path still succeeds', async () => {
+    test('default jitter path still succeeds', { skip: skipWithout('netsim') }, async () => {
       const h = makeClient({ features: [
         { name: 'netsim', options: { failTimes: 1 } },
         { name: 'retry', options: { retries: 2, minDelay: 0 } },
@@ -154,7 +164,7 @@ describe('feature', () => {
   // --- timeout --------------------------------------------------------------
   if (hasFeature('timeout')) describe('timeout', () => {
 
-    test('a slow request times out', async () => {
+    test('a slow request times out', { skip: skipWithout('netsim') }, async () => {
       const h = makeClient({ features: [
         { name: 'netsim', options: { latency: 80 } },
         { name: 'timeout', options: { ms: 10 } },
@@ -319,7 +329,7 @@ describe('feature', () => {
   // --- metrics --------------------------------------------------------------
   if (hasFeature('metrics')) describe('metrics', () => {
 
-    test('counts ok and err per op', async () => {
+    test('counts ok and err per op', { skip: skipWithout('netsim') }, async () => {
       const h = makeClient({ features: [
         { name: 'netsim', options: { failTimes: 1, failStatus: 500 } },
         { name: 'metrics', options: {} },
@@ -352,7 +362,7 @@ describe('feature', () => {
       ok(/^00-.+-.+-01$/.test(sent['traceparent']))
     })
 
-    test('records a failed span on error', async () => {
+    test('records a failed span on error', { skip: skipWithout('netsim') }, async () => {
       const h = makeClient({ features: [
         { name: 'netsim', options: { failTimes: 1, failStatus: 500 } },
         { name: 'telemetry', options: {} },
@@ -377,7 +387,7 @@ describe('feature', () => {
       strictEqual(seen[0].headers.authorization, '<redacted>')
     })
 
-    test('captures failures', async () => {
+    test('captures failures', { skip: skipWithout('netsim') }, async () => {
       const h = makeClient({ features: [
         { name: 'netsim', options: { failTimes: 1, failStatus: 500 } },
         { name: 'debug', options: {} },
@@ -391,7 +401,7 @@ describe('feature', () => {
   // --- audit ----------------------------------------------------------------
   if (hasFeature('audit')) describe('audit', () => {
 
-    test('one record per op with sink + actor', async () => {
+    test('one record per op with sink + actor', { skip: skipWithout('netsim') }, async () => {
       const sink: any[] = []
       const h = makeClient({ features: [
         { name: 'netsim', options: { failTimes: 1, failStatus: 500 } },

package/project/sdkgen-package.json

@@ -3,7 +3,7 @@
     "package": 1
   },
   "name": "@voxgig/sdkgen",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "provides": {
     "target": [
       "c",

package/src/cmp/FeatureDocs.ts

@@ -0,0 +1,100 @@
+import { each } from 'jostraca'
+
+import { KIT, getModelPath } from '../types'
+
+
+// Shared feature facts, derived from the model, for the three doc surfaces
+// that describe features: the root README summary, the per-target README
+// section, and REFERENCE.md.
+//
+// ONE SOURCE. The feature set, its defaults and its ordering constraints all
+// come from `main.kit.feature`, so a feature added to the model documents
+// itself everywhere rather than in whichever file someone remembered.
+
+type FeatureDoc = {
+  name: string
+  Name: string
+  title: string
+  transport: string
+  wraps: boolean
+  options: Array<{ name: string, value: string }>
+}
+
+
+// `transport` says how a feature attaches, and that is the whole of the
+// ordering story:
+//   wrap  wraps the transport chain — activation order IS nesting order
+//   base  installs the base transport others wrap (test)
+//   none  pipeline hooks only; order does not affect it
+function isWrapping(feat: any): boolean {
+  return 'wrap' === feat.transport
+}
+
+
+function renderValue(v: any): string {
+  if (null == v) { return '' }
+  if (Array.isArray(v)) { return '[' + v.map((x) => renderValue(x)).join(', ') + ']' }
+  if ('object' === typeof v) {
+    const keys = Object.keys(v)
+    return 0 === keys.length ? '{}' :
+      '{' + keys.map((k) => k + ': ' + renderValue(v[k])).join(', ') + '}'
+  }
+  if ('string' === typeof v) { return `'${v}'` }
+  return String(v)
+}
+
+
+// Every feature the model declares active, in a stable order, with its
+// options and their defaults.
+function featureDocs(model: any): FeatureDoc[] {
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+
+  return each(feature)
+    .filter((f: any) => false !== f.active && 'base' !== f.name)
+    .map((f: any) => {
+      const opts = (f.config && f.config.options) || {}
+      const options = Object.keys(opts).sort().map((k) => ({
+        name: k,
+        value: renderValue(opts[k]),
+      }))
+      return {
+        name: f.name,
+        Name: f.Name || f.name,
+        title: f.title || '',
+        transport: f.transport || 'none',
+        wraps: isWrapping(f),
+        options,
+      }
+    })
+    .sort((a: FeatureDoc, b: FeatureDoc) => a.name.localeCompare(b.name))
+}
+
+
+
+
+// Targets that compose transport features in a FIXED catalog order rather
+// than the order the caller activates them in.
+//
+// Every other target derives `__derived__.featureorder` from the options and
+// adds features in that order, so an ordered activation list is what fixes
+// nesting. lean has no featureorder at all — SdkFeatures.featureNames is a
+// fixed array — and its resolveFeatureOpts accepts only a map, silently
+// replacing a list with an empty one. Telling a lean reader to activate
+// features as an ordered list would therefore disable every feature they
+// asked for.
+//
+// Verify with: grep -rl featureorder tm/<target>
+const FIXED_ORDER_TARGETS = ['lean']
+
+function honoursActivationOrder(target: any): boolean {
+  return !FIXED_ORDER_TARGETS.includes(target?.name)
+}
+
+
+export {
+  featureDocs,
+  renderValue,
+  honoursActivationOrder,
+}
+
+export type { FeatureDoc }

package/src/cmp/Readme.ts

@@ -13,6 +13,7 @@ import { ReadmeEntity } from './ReadmeEntity'
 import { ReadmeUnions } from './ReadmeUnions'
 import { ReadmeHowto } from './ReadmeHowto'
 import { ReadmeExplanation } from './ReadmeExplanation'
+import { ReadmeFeatures } from './ReadmeFeatures'
 import { ReadmeRef } from './ReadmeRef'
 
 
@@ -31,6 +32,7 @@ const Readme = cmp(function Readme(props: any) {
     ReadmeModel({ target })
     ReadmeOptions({ target })
     ReadmeEntity({ target })
+    ReadmeFeatures({ target })
     ReadmeUnions({ target })
     ReadmeExplanation({ target })