@voxgig/sdkgen 4.19.1 → 4.21.0

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

@@ -0,0 +1,305 @@
+
+import {
+  Content,
+  File,
+  Folder,
+  cmp,
+  isHttpBasicAuth,
+  resolveAuthIn,
+  resolveAuthName,
+} from '@voxgig/sdkgen'
+
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
+// rather than templated.
+//
+// This was a static file at `tm/rb/utility/prepare_auth.rb` that hardcoded
+// `HEADER_AUTH = "authorization"`. apidef has always resolved the scheme's
+// `in` and `name` into `main.kit.info.security` — joplin's says
+// `in: "query", name: "token"` — and generation dropped both. The result
+// was an SDK that sent a header the API does not read and never sent the
+// query parameter it does, so it could not authenticate at all. Four repos
+// in the cedar fleet shipped that way: joplin (`token`), pipedrive
+// (`api_token`), trello (`key`), lm-umbrella (`apiKey`).
+//
+// A template cannot fix this, because the three placements need three
+// different bodies and a template has to pick one. A component emits the
+// branch this API actually uses and nothing else — no dead query code in a
+// bearer-token SDK, and no runtime `if` on a value that is fixed at
+// generation time.
+//
+// The ts port is the reference (cmp/ts/PrepareAuth_ts.ts). Two things are
+// deliberately NOT the same here, both recorded at their site below: the
+// header name is lower-cased, and the cookie clear removes our own pair
+// instead of a header that was never set.
+const PrepareAuth = cmp(async function PrepareAuth(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const active = authSwitchedOn(model)
+  const where = resolveAuthIn(model)
+  const name = resolveAuthName(model)
+  const basic = isHttpBasicAuth(model)
+
+  // RB'S LAYOUT IS FLAT, WHICH IS WHY THIS FOLDER IS OPENED HERE AND THE TS
+  // PORT OPENS NONE. In ts, Main wraps its whole body in
+  // `Folder({name:'src'})` and the utilities live at `src/utility/`, so a
+  // second `src` there would write `src/src/utility/`. Main_rb opens no such
+  // folder: `Package`, `Gitignore`, the SDK file and `Copy({from:'tm/rb'})`
+  // all land at the target root, and `Config` sits inside a `Folder({name:
+  // '.'})` that is the root too. The template this replaces was
+  // `tm/rb/utility/prepare_auth.rb`, and that Copy's root IS the target root,
+  // so the file it produced was `<root>/utility/prepare_auth.rb`. One folder,
+  // `utility`, reproduces exactly that path — and register.rb's
+  // `require_relative 'prepare_auth'` (from `utility/`) only resolves there.
+  Folder({ name: 'utility' }, () => {
+    File({ name: 'prepare_auth.' + target.ext }, () => {
+      Content(render({ Name: model.const.Name, active, where, name, basic }))
+    })
+  })
+})
+
+
+function render(spec: {
+  Name: string, active: boolean, where: string, name: string, basic: boolean
+}): string {
+  const head = `# ${spec.Name} SDK utility: prepare_auth
+require_relative 'struct/voxgig_struct'
+module ${spec.Name}Utilities
+`
+
+  const guard = `  PrepareAuth = ->(ctx) {
+    spec = ctx.spec
+    return nil, ctx.make_error("auth_no_spec", "Expected context spec property to be defined.") unless spec
+`
+
+  // NO AUTH AT ALL. A public API's SDK gets a prepare_auth that is honest
+  // about it rather than one that deletes a header nobody set.
+  if (!spec.active) {
+    return head + `  # This API declares no authentication, so there is no credential to
+  # place. The utility stays in the pipeline because make_spec calls it
+  # unconditionally, and register.rb binds it unconditionally.
+${guard}
+    return spec, nil
+  }
+end
+`
+  }
+
+  const cookie = 'cookie' === spec.where
+  const query = 'query' === spec.where
+
+  // HTTP Basic is header-only by definition: the scheme is
+  // `Authorization: Basic base64(user:pass)`. It cannot be expressed as a
+  // query parameter or a cookie, so the branch is emitted only where it can
+  // mean something.
+  const basicHere = spec.basic && 'header' === spec.where
+
+  // The constant keeps the template's name per placement, so a
+  // header-based SDK regenerates the file it already had.
+  const CRED = query ? 'QUERY_AUTH' : cookie ? 'COOKIE_AUTH' : 'HEADER_AUTH'
+
+  // HEADER NAMES ARE LOWER-CASED; QUERY AND COOKIE NAMES ARE NOT.
+  //
+  // `resolveAuthName` answers 'Authorization' by default, but the whole rb
+  // runtime spells header names in lower case — the template's
+  // `HEADER_AUTH = "authorization"`, secrets_feature.rb's
+  // `headers["authorization"]`, debug_feature.rb's mask list. A Ruby Hash key
+  // is case-sensitive, so emitting "Authorization" here would leave the
+  // secrets feature writing a SECOND, separate header and the copied
+  // pipeline_test.rb assertions on `headers["authorization"]` failing. HTTP
+  // header names are case-insensitive on the wire, so lower-casing costs
+  // nothing. Query parameter and cookie names ARE case-sensitive (`?Token=`
+  // is not `?token=`), so those go in verbatim.
+  const credName = query || cookie ? spec.name : spec.name.toLowerCase()
+
+  const consts =
+    `  ${CRED} = ${rbstr(credName)}
+` +
+    (cookie ? `  HEADER_COOKIE = "cookie"
+` : '') +
+    `  OPTION_APIKEY = "apikey"
+` +
+    (basicHere ? `  OPTION_SECRET = "secret"
+` : '') +
+    `  NOT_FOUND = "__NOTFOUND__"
+
+`
+
+  // The bag the credential lands in. A cookie rides the header bag, because
+  // a cookie IS a header.
+  const bag = query
+    ? `    query = spec.query
+`
+    : `    headers = spec.headers
+`
+
+  // Removing OUR pair, not the whole cookie header. The ts port deletes
+  // `headers[CRED_name]` for the cookie case, which is a header nothing ever
+  // set — so a stale cookie survives a withdrawn credential there. This
+  // splits the header, drops the one pair we own, and puts the rest back.
+  const dropCookie = !cookie ? '' : `
+    # Our own pair, and only ours: another cookie the caller set survives.
+    drop_cookie = ->(hs) {
+      cookie = hs[HEADER_COOKIE]
+      return unless cookie.is_a?(String)
+      rest = cookie.split("; ").reject { |pair| pair.start_with?("#{COOKIE_AUTH}=") }
+      if rest.empty?
+        hs.delete(HEADER_COOKIE)
+      else
+        hs[HEADER_COOKIE] = rest.join("; ")
+      end
+    }
+`
+
+  const clear = cookie ? 'drop_cookie.call(headers)'
+    : query ? `query.delete(${CRED})`
+      : `headers.delete(${CRED})`
+
+  const preamble = guard + `
+` + bag + `    options = ctx.client.options_map
+` + dropCookie + `
+    # Public APIs that need no auth omit the options.auth block entirely.
+    if options["auth"].nil?
+      ${clear}
+      return spec, nil
+    end
+
+    apikey = VoxgigStruct.getprop(options, OPTION_APIKEY, NOT_FOUND)
+`
+
+  const basicBlock = !basicHere ? '' : `
+    # 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 VoxgigStruct.getpath(options, "auth.basic") == true
+      secret = VoxgigStruct.getprop(options, OPTION_SECRET, NOT_FOUND)
+      no_apikey = apikey.nil? || !apikey.is_a?(String) || apikey == NOT_FOUND || apikey == ""
+      no_secret = secret.nil? || !secret.is_a?(String) || secret == NOT_FOUND || secret == ""
+
+      if no_apikey || no_secret
+        headers.delete(HEADER_AUTH)
+      else
+        auth_prefix = VoxgigStruct.getpath(options, "auth.prefix") || ""
+        # \`pack("m0")\` rather than \`Base64.strict_encode64\`: base64 left
+        # Ruby's default gems in 3.4, and pack is core.
+        b64 = ["#{apikey}:#{secret}"].pack("m0")
+        headers[HEADER_AUTH] =
+          auth_prefix.empty? ? b64 : "#{auth_prefix} #{b64}"
+      end
+
+      return spec, nil
+    end
+`
+
+  return head + consts + preamble + basicBlock + place(spec.where, clear) + `
+    return spec, nil
+  }
+end
+`
+}
+
+
+// The one thing that actually differs between placements: where the
+// credential is written, and whether the prefix travels with it.
+function place(where: string, clear: string): string {
+  // NO PREFIX IN A QUERY STRING. `?token=Bearer%20abc` is not a thing any
+  // API reads; the prefix is a header convention and is dropped here
+  // deliberately rather than silently concatenated.
+  if ('query' === where) {
+    return `
+    if apikey.nil? || (apikey.is_a?(String) && (apikey == NOT_FOUND || apikey == ""))
+      ${clear}
+    else
+      apikey_val = apikey.is_a?(String) ? apikey : ""
+      # NO PREFIX IN A QUERY STRING: \`?token=Bearer%20abc\` is not a thing
+      # any API reads, so options.auth.prefix is dropped rather than joined.
+      query[QUERY_AUTH] = apikey_val
+    end
+`
+  }
+
+  if ('cookie' === where) {
+    return `
+    # Dropped before writing, so a retry cannot accumulate the pair and a
+    # withdrawn credential leaves no stale cookie behind.
+    ${clear}
+
+    unless apikey.nil? || (apikey.is_a?(String) && (apikey == NOT_FOUND || apikey == ""))
+      apikey_val = apikey.is_a?(String) ? apikey : ""
+      # A cookie IS a header, so the pair is appended to the cookie header
+      # rather than clobbering it. No prefix: \`token=Bearer abc\` is not a
+      # cookie value any API reads.
+      existing = headers[HEADER_COOKIE]
+      pair = "#{COOKIE_AUTH}=#{apikey_val}"
+      headers[HEADER_COOKIE] =
+        (existing.is_a?(String) && !existing.empty?) ? "#{existing}; #{pair}" : pair
+    end
+`
+  }
+
+  // HEADER: the template's body, unchanged.
+  return `
+    if apikey.nil? || (apikey.is_a?(String) && (apikey == NOT_FOUND || apikey == ""))
+      ${clear}
+    else
+      auth_prefix = VoxgigStruct.getpath(options, "auth.prefix") || ""
+      apikey_val = apikey.is_a?(String) ? apikey : ""
+      # Empty prefix (raw apiKey credential) must not add a leading space.
+      headers[HEADER_AUTH] =
+        auth_prefix.empty? ? apikey_val : "#{auth_prefix} #{apikey_val}"
+    end
+`
+}
+
+
+// NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING (the py port found
+// this first; same reasoning, same fix).
+//
+// `isAuthActive` is false whenever the SPEC declares no security scheme
+// (`main.kit.info.auth: false`). That is a statement about the DEFINITION,
+// not a ban on ever sending a credential: apidef writes it for every spec
+// with no securitySchemes block, and those SDKs are still expected to honour
+// an `apikey` the caller passes. The template placed the credential
+// unconditionally, so they did.
+//
+// Gating the body on `isAuthActive` therefore does not trim dead code, it
+// deletes working authentication. MEASURED, not assumed: with the wider gate
+// this component emitted the no-op for generatedcompile's own fixture
+// (`main: kit: info: { ... auth: false }`) and two running rb lanes went red
+// —
+//
+//   rb: auth null beats an explicit apikey
+//     FAIL: baseline broken: an ordinary apikey was not sent
+//   rb: the secrets feature runs with the feature active
+//     expected the authorization header to carry OPTKEY01, got: nil
+//
+// So the no-op is emitted only when the PROJECT says so: `config.auth.active:
+// false`, an explicit per-SDK switch nobody sets by accident. A spec that is
+// merely silent keeps the credential path it has always had.
+function authSwitchedOn(model: any): boolean {
+  const auth = getModelPath(model, `main.${KIT}.config.auth`,
+    { only_active: false, required: false })
+  return !(null != auth && false === auth.active)
+}
+
+
+// A Ruby double-quoted literal. `#` is escaped only where it would OPEN an
+// interpolation, matching utility_rb.formatRubyValue.
+function rbstr(s: string): string {
+  return '"' + String(s)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/#(?=[{$@])/g, '\\#') + '"'
+}
+
+
+export {
+  PrepareAuth
+}

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

@@ -20,6 +20,7 @@ Use \`Helpers.to_map()\` to safely validate that a value is a hash.
 rb/
 ├── ${model.const.Name}_sdk.rb       -- Main SDK module
 ├── config.rb                  -- Configuration
+├── schema.rb                  -- Generated option + entity specs
 ├── features.rb                -- Feature factory
 ├── core/                      -- Core types and context
 ├── entity/                    -- Entity implementations

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

@@ -0,0 +1,70 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+  rawStringLiteral,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
+//
+// The ruby peer of src/cmp/ts/Schema_ts.ts. Same two exports, same source —
+// OPTSPEC from `main.kit.optspec` plus each feature's own `config.options`,
+// ENTITYSPEC from the entity field sentinels — built by the shared helpers,
+// so what ruby validates against and what ts validates against cannot drift.
+//
+// EMBEDDED AS JSON, PARSED AT LOAD, the mechanism config.rb already uses for
+// the model above the size threshold, and SINGLE-quoted for the reason
+// recorded there: a double-quoted ruby string would interpolate any `#{` the
+// model happens to contain.
+//
+// The round-trip is exact because the spec holds only strings and booleans —
+// pinned by "strings and booleans only, so the JSON round-trip is lossless"
+// in ts/test/optspec.test.ts.
+const Schema = cmp(async function Schema(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+
+  const optspec = optionSpec(model, target.name)
+  const entityspec = entitySpecMap(model, target.name) || {}
+
+  File({ name: 'schema.' + target.ext }, () => {
+    Content(`# ${model.const.Name} ${target.Name} SDK: generated schemas. Do not edit.
+#
+# Generated from the model: \`main.kit.optspec\` and each feature's
+# \`config.options\` for OPTSPEC; entity \`fields[].type\` for ENTITYSPEC.
+
+require 'json'
+
+module ${model.const.Name}Schema
+
+  OPTSPEC_DATA = ${rawStringLiteral(JSON.stringify(optspec))}.freeze
+
+  ENTITYSPEC_DATA = ${rawStringLiteral(JSON.stringify(entityspec))}.freeze
+
+  # Parsed ONCE, at load. The spec is read on every client construction and
+  # never mutated, so a per-call parse would be pure waste — and sharing the
+  # hash is safe for the same reason: make_options validates AGAINST it and
+  # writes into the options, never into the spec.
+  OPTSPEC = JSON.parse(OPTSPEC_DATA).freeze
+
+  ENTITYSPEC = JSON.parse(ENTITYSPEC_DATA).freeze
+
+end
+`)
+  })
+})
+
+
+export {
+  Schema
+}

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

@@ -8,6 +8,8 @@ import {
   each,
   isAuthActive,
   isConfigData,
+  resolveAuthIn,
+  resolveAuthName,
   resolveAuthPrefix,
   targetFeatures,
 } from '@voxgig/sdkgen'
@@ -58,7 +60,45 @@ const Config = cmp(async function Config(props: any) {
   // slug/version/target identity fields (station descriptor input, mirrors
   // Config_ts) - both reps below render from this same def, so the data
   // and literal branches pick the fields up together.
-  const { def: config, json: configJson } = configDefinition(model, target.name)
+  const { def: config, json: baseJson } = configDefinition(model, target.name)
+
+  // `in` and `name` TRAVEL WITH THE PREFIX NOW.
+  //
+  // apidef resolved both from the spec's securityScheme all along and this
+  // generator dropped them, so an apiKey-in-query API got an `authorization`
+  // header it does not read (see PrepareAuth_rust). The generated
+  // prepare_auth is built from the same two values, and the config carries
+  // them so the placement is a visible, overridable runtime option beside
+  // auth.prefix - which is also what keeps the SDK from rejecting its own
+  // config: the auth optspec in tm/rust/utility/make_options.rs is a CLOSED
+  // map, and an undeclared key there fails validate with "Unexpected keys at
+  // field auth".
+  //
+  // Emitted ONLY when they differ from header/Authorization, so a
+  // header-based SDK's config.rs is byte-identical to what it generated
+  // before. Both representations are patched through the one object, so the
+  // literal (formatRustValue) and the data rep (rustRawString) cannot
+  // disagree - the json is re-derived from the def, exactly as
+  // configDefinition derives it.
+  const authIn = resolveAuthIn(model)
+  const authName = resolveAuthName(model)
+  let configJson = baseJson
+
+  if (authActive && null != config.options && null != config.options.auth) {
+    let changed = false
+    if ('header' !== authIn) {
+      config.options.auth.in = authIn
+      changed = true
+    }
+    if ('Authorization' !== authName) {
+      config.options.auth.name = authName
+      changed = true
+    }
+    if (changed) {
+      configJson = JSON.stringify(config)
+    }
+  }
+
   const asData = isConfigData(configJson, configReprSetting(model))
 
   File({ name: 'config.' + target.ext }, () => {

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

@@ -24,6 +24,8 @@ import {
 
 import { Package } from './Package_rust'
 import { Config } from './Config_rust'
+import { Schema } from './Schema_rust'
+import { PrepareAuth } from './PrepareAuth_rust'
 import { Gitignore } from './Gitignore_rust'
 import { MainEntity } from './MainEntity_rust'
 import { EntityBase } from './EntityBase_rust'
@@ -67,6 +69,21 @@ const Main = cmp(async function Main(props: any) {
     }
   })
 
+  // utility/prepare_auth.rs is GENERATED, not templated: where the
+  // credential goes (header / query / cookie, and under what name) is a
+  // fact about the API, and tm/ can only hold one answer. See
+  // PrepareAuth_rust.
+  //
+  // AT ROOT LEVEL, and outside the `core` Folder below. The rust crate root
+  // IS the target root - lib.rs, core/, feature/ and utility/ all sit there
+  // - the component opens `utility` itself, and that is the same path
+  // `Copy({from:'tm/rust'})` used for the template it replaces. Calling it
+  // beside Config, inside `Folder({name:'core'})`, would emit
+  // core/utility/prepare_auth.rs instead: a file no module declares, so
+  // rustc never compiles it, while utility/mod.rs's `pub mod prepare_auth;`
+  // keeps binding whatever utility/ actually holds.
+  PrepareAuth({ target })
+
   // Generated core files: the client (sdk.rs), the API config and the
   // branded error type.
   Folder({ name: 'core' }, () => {
@@ -93,6 +110,8 @@ const Main = cmp(async function Main(props: any) {
 
     Config({ target })
 
+    Schema({ target })
+
     SdkError({ target })
   })