@voxgig/sdkgen 4.34.1 → 4.34.2

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/utility/ResultUtil.swift

@@ -67,7 +67,7 @@ private func stripAction(_ reqdata: Value) -> Value {
 
 // A header, cookie or query argument travels where prepareHeadersUtil or
 // prepareQueryUtil sends it, so the body is built from the request data
-// without it, unless the entity declares it as a field too.
+// without it, unless the point marks it as a field the body keeps.
 private func routedArgNames(_ ctx: Context) -> [String] {
   return (callArgs(ctx, "header") + callArgs(ctx, "cookie") + callArgs(ctx, "query")).map { $0.name }
     .filter { !fieldArg(ctx, $0) }
@@ -143,11 +143,43 @@ extension Utility {
   public final class CleanConfig {
     public var active = true
     public var keys: [String] = []
-    public var values: [String] = []
     public var mask = "[redacted]"
     public var hint = 0
     public var min = 4
+
+    // Requests on other threads clean while one registers, so the registry
+    // is read and written under its own lock.
+    private let lock = NSLock()
+    private var registry: [String] = []
+
+    public var values: [String] {
+      get {
+        lock.lock()
+        defer { lock.unlock() }
+        return registry
+      }
+      set {
+        lock.lock()
+        defer { lock.unlock() }
+        registry = newValue
+      }
+    }
+
     public init() {}
+
+    // The forms not yet registered are added, longest first, in one step.
+    func register(_ forms: [String]) {
+      lock.lock()
+      defer { lock.unlock() }
+      var changed = false
+      for form in forms where form.count >= min && !registry.contains(form) {
+        registry.append(form)
+        changed = true
+      }
+      if changed {
+        registry.sort { $0.count > $1.count }
+      }
+    }
   }
 }
 
@@ -228,16 +260,7 @@ private func cleanForms(_ value: String) -> [String] {
 func cleanAddUtil(_ ctx: Context, _ value: Value) {
   let cfg = cleanConfigOf(ctx)
   guard let s = value.asString, s.count >= cfg.min else { return }
-  var changed = false
-  for form in cleanForms(s) {
-    if form.count >= cfg.min && !cfg.values.contains(form) {
-      cfg.values.append(form)
-      changed = true
-    }
-  }
-  if changed {
-    cfg.values.sort { $0.count > $1.count }
-  }
+  cfg.register(cleanForms(s))
 }
 
 // Every scalar under a sensitive name, at any depth and of any shape: a

package/project/.sdk/tm/swift/Tests/ProjectNameSDKTests/ConcurrencyTest.swift

@@ -0,0 +1,214 @@
+// Requests in flight at once on one client. Each registers and cleans
+// secrets through the one registry the client holds. A context keeps its own
+// copy of the operation cache, so requests share no cache to race on.
+
+import Foundation
+import XCTest
+
+@testable import ProjectNameSdk
+
+final class ConcurrencyTest: XCTestCase {
+  private static let rounds = 200
+  private static let width = 8
+  private static let ops = 32
+  private static let masked = "a [redacted] b [redacted] c"
+
+  // What the racing threads report, under one lock.
+  private final class Outcome {
+    private let lock = NSLock()
+    private var notes: [String] = []
+    private var left: Int
+
+    init(registering: Int) {
+      left = registering
+    }
+
+    func note(_ what: String) {
+      lock.lock()
+      defer { lock.unlock() }
+      notes.append(what)
+    }
+
+    var first: String? {
+      lock.lock()
+      defer { lock.unlock() }
+      return notes.first
+    }
+
+    func registered() {
+      lock.lock()
+      defer { lock.unlock() }
+      left -= 1
+    }
+
+    var registering: Bool {
+      lock.lock()
+      defer { lock.unlock() }
+      return 0 < left
+    }
+  }
+
+  // A live client whose transport answers at once.
+  private static func liveClient() -> ProjectNameSDK {
+    let fetcher: FetcherFunc = { _, _, _ in
+      let res = VMap()
+      res.entries["status"] = .int(200)
+      res.entries["statusText"] = .string("OK")
+      res.entries["headers"] = .map(VMap())
+      res.entries["json"] = .nat({ () -> Value in .map(vm(("ok", .bool(true)))) } as NativeCall0)
+      return .map(res)
+    }
+    return ProjectNameSDK(vm(
+      ("base", .string("http://concurrency.test/api")),
+      ("allow", .map(vm(("op", .string("direct"))))),
+      ("utility", .map(vm(("fetcher", .nat(fetcher)))))))
+  }
+
+  // Runs body on width threads, released once every one is waiting; a
+  // thread's error is noted.
+  private static func atOnce(_ outcome: Outcome, _ body: @escaping (Int) throws -> Void) {
+    let ready = DispatchSemaphore(value: 0)
+    let start = DispatchSemaphore(value: 0)
+    let done = DispatchGroup()
+    for n in 0..<width {
+      done.enter()
+      let thread = Thread {
+        ready.signal()
+        start.wait()
+        do {
+          try body(n)
+        } catch {
+          outcome.note("threw: \(error)")
+        }
+        done.leave()
+      }
+      thread.start()
+    }
+    for _ in 0..<width {
+      ready.wait()
+    }
+    for _ in 0..<width {
+      start.signal()
+    }
+    done.wait()
+  }
+
+  private static func addedSecret(_ round: Int, _ n: Int, _ k: Int) -> String {
+    return "ADDED-SECRET-\(round)-\(n)-\(k)"
+  }
+
+  // Registers thread n's secrets, then counts the thread out.
+  private static func registerSecrets(
+    _ utility: Utility, _ root: Context, _ round: Int, _ n: Int, _ outcome: Outcome
+  ) {
+    defer { outcome.registered() }
+    for k in 0..<ops {
+      utility.cleanAdd(root, .string(addedSecret(round, n, k)))
+    }
+  }
+
+  // The first secret registered in the round that a clean leaves raw.
+  private static func unmaskedSecret(_ utility: Utility, _ root: Context, _ round: Int) -> String? {
+    for n in 0..<(width / 2) {
+      for k in 0..<ops {
+        let added = addedSecret(round, n, k)
+        if utility.clean(root, .string(added)).asString != "[redacted]" {
+          return added
+        }
+      }
+    }
+    return nil
+  }
+
+  func testConcurrentFirstRequestsSucceed() {
+    for round in 0..<ConcurrencyTest.rounds {
+      // A fresh client each round, so every request in it is a first request.
+      let client = ConcurrencyTest.liveClient()
+      let outcome = Outcome(registering: 0)
+      ConcurrencyTest.atOnce(outcome) { n in
+        let res = client.direct(vm(("path", .string("p\(n)"))))
+        if gp(res, "ok") != .bool(true) {
+          outcome.note("request \(n) failed: \(stringify(.map(res)))")
+        }
+      }
+      if let first = outcome.first {
+        XCTFail("round \(round): \(first)")
+        return
+      }
+    }
+  }
+
+  // Secrets registered on some threads while others clean: every clean masks
+  // what was registered before it, the longer secret whole, and no
+  // registration is lost.
+  func testConcurrentRegistrationKeepsEverySecretMasked() {
+    let half = ConcurrencyTest.width / 2
+    let masked = ConcurrencyTest.masked
+    for round in 0..<(ConcurrencyTest.rounds / 4) {
+      let client = ConcurrencyTest.liveClient()
+      let utility = client.getUtility()
+      let root = client.getRootCtx()
+      let inner = "INNER-SECRET-\(round)"
+      utility.cleanAdd(root, .string(inner))
+      utility.cleanAdd(root, .string("OUTER-\(inner)-TAIL"))
+      let text = "a \(inner) b OUTER-\(inner)-TAIL c"
+      XCTAssertEqual(utility.clean(root, .string(text)).asString, masked, "round \(round)")
+
+      let outcome = Outcome(registering: half)
+      ConcurrencyTest.atOnce(outcome) { n in
+        if n < half {
+          ConcurrencyTest.registerSecrets(utility, root, round, n, outcome)
+          return
+        }
+        while outcome.registering {
+          let got = utility.clean(root, .string(text)).asString ?? ""
+          if got != masked {
+            outcome.note("cleaned to: \(got)")
+            return
+          }
+        }
+      }
+      if let first = outcome.first {
+        XCTFail("round \(round) \(first)")
+        return
+      }
+      if let raw = ConcurrencyTest.unmaskedSecret(utility, root, round) {
+        XCTFail("round \(round): \(raw) was registered but not masked")
+        return
+      }
+    }
+  }
+
+  // Requests on one client while secrets register on it: each request copies
+  // the client's options, the registry among them.
+  func testConcurrentRequestsSurviveRegistration() {
+    let half = ConcurrencyTest.width / 2
+    for round in 0..<(ConcurrencyTest.rounds / 4) {
+      let client = ConcurrencyTest.liveClient()
+      let utility = client.getUtility()
+      let root = client.getRootCtx()
+      let outcome = Outcome(registering: half)
+      ConcurrencyTest.atOnce(outcome) { n in
+        if n < half {
+          ConcurrencyTest.registerSecrets(utility, root, round, n, outcome)
+          return
+        }
+        while outcome.registering {
+          let res = client.direct(vm(("path", .string("p\(n)"))))
+          if gp(res, "ok") != .bool(true) {
+            outcome.note("a request failed: \(stringify(.map(res)))")
+            return
+          }
+        }
+      }
+      if let first = outcome.first {
+        XCTFail("round \(round) \(first)")
+        return
+      }
+      if let raw = ConcurrencyTest.unmaskedSecret(utility, root, round) {
+        XCTFail("round \(round): \(raw) was registered but not masked")
+        return
+      }
+    }
+  }
+}

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

@@ -37,7 +37,7 @@ function stripAction(reqdata: any) {
 
 // A header, cookie or query argument travels where prepareHeaders or
 // prepareQuery sends it, so the body is built from the request data without
-// it, unless the entity declares it as a field too.
+// it, unless the point marks it as a field the body keeps.
 function routedArgNames(ctx: Context): string[] {
   return [...callArgs(ctx, 'header'), ...callArgs(ctx, 'cookie'), ...callArgs(ctx, 'query')]
     .map((arg) => arg.name)

package/project/.sdk/tm/zig/core/utility.zig

@@ -2164,7 +2164,7 @@ fn strip_action(reqdata: Value) Value {
 
 // A header, cookie or query argument travels where prepare_headers_util or
 // prepare_query_util sends it, so the body is built from the request data
-// without it, unless the entity declares it as a field too.
+// without it, unless the point marks it as a field the body keeps.
 fn routed_arg_names(ctx: *Context) [][]const u8 {
     var names: std.ArrayList([]const u8) = .empty;
     for ([_][]const u8{ "header", "cookie", "query" }) |kind| {

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

@@ -206,17 +206,19 @@ fn pick_point(points: Value) Value {
     return point;
 }
 
+// Each name is read from its arg: this struct port's `$EACH` transform answers
+// null for every `$KEY.name`, where the other ports answer the names.
 fn reqd_names(point: Value, kind: []const u8) Value {
     const args_path = h.getpath(&.{ "args", kind }, point);
     const reqd_args = vs.select(h.A(), args_path, h.jo(&.{.{ "reqd", h.vbool(true) }})) catch return h.olist();
-    // transform reports collected injection errors beside the value; .out is
-    // the value itself, errors or not.
-    const tres = vs.transform(h.A(), reqd_args, h.ja(&.{
-        h.vstr("`$EACH`"),
-        h.vstr(""),
-        h.vstr("`$KEY.name`"),
-    })) catch return h.olist();
-    return tres.out;
+    const names = h.olist();
+    if (reqd_args == .array) {
+        for (reqd_args.array.data.items) |arg| {
+            const name = h.getp(arg, "name");
+            if (name == .string) names.array.append(name) catch {};
+        }
+    }
+    return names;
 }
 
 fn build_args(ctx: *Context, args: Value) Value {

package/project/sdkgen-package.json

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

package/src/cmp/ReadmeErrors.ts

@@ -8,8 +8,8 @@ import {
 } from '../types'
 
 import { entityIdField, pickExampleEntity } from '../helpers/opShape'
-import { primaryOpCall } from '../helpers/opExample'
-import type { ExampleLang, PrimaryCall } from '../helpers/opExample'
+import { helperLang, primaryOpCall } from '../helpers/opExample'
+import type { PrimaryCall } from '../helpers/opExample'
 import { safeVarName, exampleVarName } from '../helpers/naming'
 
 
@@ -28,7 +28,7 @@ const DEFAULT_LANG: LangErrors = {
 \`\`\`ts
 try {
   const ${call.resultVar} = await ${call.expr}
-  console.log(${call.resultVar})
+  console.log(${'list' === op ? call.resultVar + '.map((item) => item.data())' : call.resultVar + '.data()'})
 } catch (err) {
   console.error('${op} failed:', err)
 }
@@ -62,7 +62,7 @@ const LANGS: Record<string, LangErrors> = {
 \`\`\`python
 try:
     ${call.resultVar} = ${call.expr}
-    print(${call.resultVar})
+    print(${'list' === op ? '[item.data_get() for item in ' + call.resultVar + ']' : call.resultVar + '.data_get()'})
 except Exception as err:
     print(f"${op} failed: {err}")
 \`\`\`
@@ -228,7 +228,7 @@ const ReadmeErrors = cmp(function ReadmeErrors(props: any) {
     const eName = ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))
     const eLower = exampleVarName(eName.toLowerCase(), target.name)
     const idF = entityIdField(ex)
-    const call = primaryOpCall(target.name as ExampleLang, eName, eLower, primaryOp, idF, ex)
+    const call = primaryOpCall(helperLang(target.name), eName, eLower, primaryOp, idF, ex)
     Content(lang.entity(call, primaryOp))
   }
 

package/src/cmp/ReadmeExplanation.ts

@@ -12,8 +12,7 @@ import {
 import { optionalComponent } from '../helpers/optional'
 
 import { entityIdField, pickExampleEntity } from '../helpers/opShape'
-import { idLiteral, matchArg, dataArg } from '../helpers/opExample'
-import type { ExampleLang } from '../helpers/opExample'
+import { helperLang, idLiteral, matchArg, listMatchArg, dataArg } from '../helpers/opExample'
 import { safeVarName, exampleVarName, phpEntityAccessor } from '../helpers/naming'
 
 
@@ -232,7 +231,7 @@ const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
   // skipped (a direct()-only SDK has no entity op to illustrate).
   const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
   const { entity: ex, primaryOp } = pickExampleEntity(entity || {})
-  const lname = target.name as ExampleLang
+  const lname = helperLang(target.name)
   const hasEntityExample = !!(ex && primaryOp)
 
   let eName = 'Entity', eLower = 'entity', stateArg = '', matchIdF: string | null = null, idLit = ''
@@ -246,9 +245,9 @@ const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
     // match compiles.
     idLit = idLiteral(ex, primaryOp as string, idF)
     // Language-correct call argument for the primary op: a match for
-    // load/remove, a required-field body for create/update, nothing for list.
+    // load/remove/list, a required-field body for create/update.
     if ('list' === primaryOp) {
-      stateArg = 'go' === target.name ? 'nil' : ''
+      stateArg = listMatchArg(lname, ex)
     } else if (isMatchOp) {
       stateArg = matchArg(lname, ex, primaryOp as string, idF, idLit)
     } else {

package/src/cmp/ReadmeQuick.ts

@@ -2,17 +2,19 @@
 import { Content } from 'jostraca'
 import { cmp } from '../helpers/component'
 
+import { credentialPlacement } from '../utility'
 import { optionalComponent } from '../helpers/optional'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$ } = props
+  const placement = credentialPlacement(ctx$.model)
 
   Content(`
 ## Tutorial: your first API call
 
 This tutorial walks through creating a client, listing entities, and
-loading a specific record.
+loading a specific record.${'' === placement ? '' : ' ' + placement}
 
 `)
 

package/src/cmp/ReadmeTop.ts

@@ -7,6 +7,7 @@ import {
   getModelPath
 } from '../types'
 
+import { credentialPlacement } from '../utility'
 import { optionalComponent } from '../helpers/optional'
 import { featureDocs } from './FeatureDocs'
 import type { FeatureDoc } from './FeatureDocs'
@@ -14,11 +15,11 @@ import type { FeatureDoc } from './FeatureDocs'
 import {
   entityPrimaryOp, entityIdField, opRequestShape, entityPath, entityActions,
 } from '../helpers/opShape'
-import { matchArg, idLiteral, primaryOpCall } from '../helpers/opExample'
+import { EXAMPLE_LANGS, matchArg, listMatchArg, idLiteral, primaryOpCall } from '../helpers/opExample'
 import { mcpTools, MCP_WRITE_OPS } from '../helpers/mcpTools'
 import type { ExampleLang, PrimaryCall } from '../helpers/opExample'
-import { canonKey } from '../helpers/canonType'
-import { safeVarName, exampleVarName } from '../helpers/naming'
+import { canonScalarKey } from '../helpers/canonType'
+import { safeVarName, exampleVarName, jsKey } from '../helpers/naming'
 import { modelText } from '../helpers/text'
 
 import {
@@ -43,7 +44,8 @@ const VOXGIG_SDK = 'https://voxgig.com/sdk/'
 // type sentinel — mirrors the per-language `exampleValue`, but inline because
 // this neutral component renders the intro `ts` block directly.
 function tsExampleLiteral(type: any): string {
-  const k = canonKey(type)
+  const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '[]'
@@ -70,10 +72,6 @@ function isConsumer(target: any): boolean {
 }
 
 
-// The languages the example helpers can write, in the order a reader is
-// likeliest to want one.
-const EXAMPLE_LANGS: ExampleLang[] = ['ts', 'js', 'py', 'go', 'php', 'rb', 'lua']
-
 const EXAMPLE_FENCE: Record<string, string> = {
   ts: 'ts', js: 'js', py: 'python', go: 'go', php: 'php', rb: 'ruby', lua: 'lua',
 }
@@ -288,8 +286,7 @@ ${aboutMd.trim()}
       const primaryOp = entityPrimaryOp(exEnt)
       let exCall = ''
       const exIdField = entityIdField(exEnt)
-      const exListArg = matchArg('ts', exEnt, 'list', exIdField,
-        idLiteral(exEnt, 'list', exIdField))
+      const exListArg = listMatchArg('ts', exEnt)
       const exLoadArg = matchArg('ts', exEnt, 'load', exIdField,
         idLiteral(exEnt, 'load', exIdField))
 
@@ -308,7 +305,7 @@ ${aboutMd.trim()}
             (it.name !== exIdF && it.name !== 'id') || !it.optional)
         const required = shapeItems.filter((it: any) => !it.optional)
         const chosen = required.length ? required : shapeItems.slice(0, 3)
-        const bodyLines = chosen.map((it: any) => `  ${it.name}: ${tsExampleLiteral(it.type)},`)
+        const bodyLines = chosen.map((it: any) => `  ${jsKey(it.name)}: ${tsExampleLiteral(it.type)},`)
         const body = bodyLines.length ? `\n${bodyLines.join('\n')}\n` : ''
         exCall = `const ${exLower} = await client.${ex}().${primaryOp}({${body}})`
       }
@@ -413,8 +410,9 @@ network, and no credentials:
       if (LeadQuick) {
         LeadQuick['ReadmeTopQuick']({ target: leadTarget })
       }
+      const placement = credentialPlacement(model)
       Content(`
-See the [${leadTarget.title} README](${leadTarget.name}/README.md) for the full guide.
+${'' === placement ? '' : placement + '\n\n'}See the [${leadTarget.title} README](${leadTarget.name}/README.md) for the full guide.
 
 `)
     }

package/src/helpers/definitionPlan.ts

@@ -156,7 +156,7 @@ function definitionPlan(ctx$: any): DefinitionPoint[] {
         const rawBody = recorded && BODY_OPS.includes(op) ?
           rawRequestBody(facts) : undefined
 
-        // An argument the request body declares too goes out in both, from one value.
+        // An argument the request body declares writable goes out in both, from one value.
         const declared = ('create' === op || 'update' === op) && null == rawBody ?
           bodyProperties(facts) : []
         const bodyArgs = [...new Set([...headers, ...cookies].map((a: any) => a.name)
@@ -281,14 +281,18 @@ function rawRequestBody(facts: any): { media: string[], text: boolean } | undefi
 }
 
 
-// The top-level properties a JSON request body declares, an allOf's parts included.
+// The top-level properties a JSON request body declares, an allOf's parts
+// included, less any that a declaration marks read-only.
 function bodyProperties(facts: any): string[] {
   const content = facts.requestBody?.content
   const schema = null != content && 'object' === typeof content ?
     content[Object.keys(content).find((t) => /json/i.test(t)) ?? '']?.schema :
     (facts.parameters || []).find((p: any) => 'body' === p?.in)?.schema
-  return [schema, ...(Array.isArray(schema?.allOf) ? schema.allOf : [])]
-    .flatMap((part: any) => Object.keys(part?.properties || {}))
+  const props = [schema, ...(Array.isArray(schema?.allOf) ? schema.allOf : [])]
+    .flatMap((part: any) => Object.entries(part?.properties || {}))
+  const readOnly = new Set(props.filter(([, prop]: [string, any]) => true === prop?.readOnly)
+    .map(([name]) => name))
+  return props.map(([name]) => name).filter((name) => !readOnly.has(name))
 }
 
 

package/src/helpers/naming.ts

@@ -88,7 +88,7 @@ const RB_SDK_CONSTANTS = new Set<string>([
   // shipped only when that feature is selected, but declared at the top
   // level when it is
   'VoxgigSekreto', 'VoxgigPlugin',
-  'ExistsTest', 'FeatureCorpusTest', 'FeatureTest', 'NetsimTest',
+  'ConcurrencyTest', 'ExistsTest', 'FeatureCorpusTest', 'FeatureTest', 'NetsimTest',
   'PipelineTest', 'PrimaryUtilityTest', 'ReadmeExamplesTest',
   'SecretsFeatureTest',
   'TestHookFeature', 'TestInitFeature',
@@ -459,9 +459,16 @@ function jsProp(obj: string, name: string): string {
 
 // A safe JS/TS OBJECT-LITERAL key for a spec-derived field name: bare when
 // the name is a valid identifier, single-quoted otherwise. `{ 3ds_session_id:
-// 1 }` is a syntax error (TS1351) — doc examples must quote such keys.
+// 1 }` is a syntax error (TS1351) — doc examples must quote such keys. A bare
+// or quoted `__proto__` sets the prototype, so it is computed.
 function jsKey(name: string): string {
-  return JS_IDENT.test(name) ? name : `'${name}'`
+  if ('__proto__' === name) return `['__proto__']`
+  return JS_IDENT.test(name) ? name : jsQuote(name)
+}
+
+
+function jsQuote(s: string): string {
+  return "'" + JSON.stringify(s).slice(1, -1).replace(/\\"/g, '"').replace(/'/g, "\\'") + "'"
 }
 
 
@@ -471,7 +478,7 @@ const LUA_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/
 function luaKey(name: string): string {
   return LUA_IDENT.test(name) && !isReservedName(name, 'lua')
     ? name
-    : `["${name}"]`
+    : `["${name.replace(/[\\"]/g, '\\$&').replace(/\n/g, '\\n').replace(/\r/g, '\\r')}"]`
 }
 
 
@@ -511,6 +518,7 @@ export {
   jsProp,
   jsOptProp,
   jsKey,
+  jsQuote,
   luaKey,
   prefixLeadingDigit,
 }