@voxgig/sdkgen 4.19.1 → 4.21.0

package/project/.sdk/src/cmp/go/PrepareAuth_go.ts

@@ -0,0 +1,322 @@
+
+import {
+  Content,
+  File,
+  Folder,
+  cmp,
+  goModule,
+  isHttpBasicAuth,
+  resolveAuthIn,
+  resolveAuthName,
+  resolveAuthPrefix,
+} 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 is the go peer of PrepareAuth_ts; read that
+// one first, it carries the full account of the defect.
+//
+// This was a static file at `tm/go/utility/prepare_auth.go` that hardcoded
+//
+//   const headerAuth = "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, so the SDK sent a header the API does not
+// read and never sent the query parameter it does.
+//
+// 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 fixed at generation
+// time. Go makes that stricter than most targets: an unused local is a
+// COMPILE ERROR, so a file that resolved `authPrefix` and then dropped it
+// for a query placement would not build at all.
+const PrepareAuth = cmp(async function PrepareAuth(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  // The generated source cannot use the `GOMODULE` / `github.com/voxgig/struct`
+  // placeholders: those are rewritten by Main's `Copy({from:'tm/go'})`, and
+  // this file never travels through that Copy. The real import paths go in
+  // here, the same way EntityTypes_go resolves them.
+  const gomodule = goModule(model, target.name)
+
+  const active = isAuthActive_go(model)
+  const where = resolveAuthIn(model)
+  const name = resolveAuthName(model)
+  const prefix = resolveAuthPrefix(model)
+  const basic = isHttpBasicAuth(model)
+
+  // FOLDER NESTING. Main_go opens NO folder around this call: go's layout is
+  // flat at the target root (core/, utility/, feature/, entity/, test/), the
+  // template this replaces lived at `tm/go/utility/prepare_auth.go`, and
+  // `Copy({from:'tm/go'})` lands it at `<root>/utility/`. So the `utility`
+  // folder is opened HERE, exactly as EntityTypes_go opens `entity`.
+  //
+  // The call site matters as much: Config is inside `Folder({name:'core'})`,
+  // and putting PrepareAuth beside it would write `core/utility/prepare_auth.go`
+  // — a second `package utility` nobody imports, while the registrar keeps
+  // calling whatever `utility/` still holds. Main_go calls this at ROOT level.
+  Folder({ name: 'utility' }, () => {
+    File({ name: 'prepare_auth.' + target.ext }, () => {
+      Content(render({ gomodule, active, where, name, prefix, basic }))
+    })
+  })
+})
+
+
+type AuthSpec = {
+  gomodule: string
+  active: boolean
+  where: string
+  name: string
+  prefix: string
+  basic: boolean
+}
+
+
+function render(spec: AuthSpec): string {
+
+  // NO AUTH AT ALL. A public API's SDK gets a prepareAuth that is honest
+  // about it rather than one that deletes a header nobody set. `vs` is left
+  // out of the imports deliberately — go rejects an unused import.
+  if (!spec.active) {
+    return `package utility
+
+import (
+	"${spec.gomodule}/core"
+)
+
+// This API declares no authentication, so there is no credential to place.
+// The function stays in the pipeline because makeSpec calls it
+// unconditionally.
+func prepareAuthUtil(ctx *core.Context) (*core.Spec, error) {
+	spec := ctx.Spec
+	if spec == nil {
+		return nil, ctx.MakeError("auth_no_spec",
+			"Expected context spec property to be defined.")
+	}
+
+	return spec, nil
+}
+`
+  }
+
+  // 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 — and base64 is imported only then.
+  const withBasic = spec.basic && 'header' === spec.where
+
+  const head = `package utility
+
+import (
+${withBasic ? `	"encoding/base64"
+
+` : ''}	vs "${spec.gomodule}/utility/struct"
+
+	"${spec.gomodule}/core"
+)
+
+const credName = "${gostr(credLiteral(spec.where, spec.name))}"
+${'cookie' === spec.where ? `const cookieHeader = "cookie"
+` : ''}const optionApikey = "apikey"
+${withBasic ? `const optionSecret = "secret"
+` : ''}const notFound = "__NOTFOUND__"
+
+func prepareAuthUtil(ctx *core.Context) (*core.Spec, error) {
+	spec := ctx.Spec
+	if spec == nil {
+		return nil, ctx.MakeError("auth_no_spec",
+			"Expected context spec property to be defined.")
+	}
+
+	${bagName(spec.where)} := spec.${bagField(spec.where)}
+	options := ctx.Client.OptionsMap()
+
+	// Public APIs that need no auth omit the options.auth block entirely.
+	if options["auth"] == nil {
+		${clear(spec.where)}
+		return spec, nil
+	}
+
+	apikey := vs.GetProp(options, optionApikey, notFound)
+
+	skip := false
+	if apikey == nil {
+		skip = true
+	} else if apikeyStr, ok := apikey.(string); ok &&
+		(apikeyStr == notFound || apikeyStr == "") {
+		skip = true
+	}
+`
+
+  const basicBlock = !withBasic ? '' : `
+	// 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 basicAuth, _ := vs.GetPath(options, []any{"auth", "basic"}).(bool); basicAuth {
+		secret := vs.GetProp(options, optionSecret, notFound)
+
+		noSecret := false
+		if secret == nil {
+			noSecret = true
+		} else if secretStr, ok := secret.(string); ok &&
+			(secretStr == notFound || secretStr == "") {
+			noSecret = true
+		}
+
+		if skip || noSecret {
+			${clear(spec.where)}
+		} else {
+			apikeyVal, _ := apikey.(string)
+			secretVal, _ := secret.(string)
+			b64 := base64.StdEncoding.EncodeToString([]byte(apikeyVal + ":" + secretVal))
+
+			basicPrefix := ""
+			if ap := vs.GetPath(options, []any{"auth", "prefix"}); ap != nil {
+				basicPrefix, _ = ap.(string)
+			}
+			// Empty prefix (raw apiKey credential) must not add a leading space.
+			if basicPrefix == "" {
+				${bagName(spec.where)}[credName] = b64
+			} else {
+				${bagName(spec.where)}[credName] = basicPrefix + " " + b64
+			}
+		}
+
+		return spec, nil
+	}
+`
+
+  return head + basicBlock + `
+	if skip {
+		${clear(spec.where)}
+	} else {
+${place(spec.where)}
+	}
+
+	return spec, nil
+}
+`
+}
+
+
+// The credential's key, as it goes into the bag.
+//
+// A HEADER name is lowercased. HTTP header names are case-insensitive
+// (RFC 9110 5.1) and go's `req.Header.Set` canonicalises on the wire, so
+// nothing changes over the socket — but this SDK's own header map is keyed
+// in lowercase throughout (`content-type`, and the `authorization` that the
+// generated pipeline/feature/secrets tests assert on), and the shipped
+// `prepare_auth.go` said `"authorization"`. Emitting the resolver's
+// title-cased default here would have left every header SDK's own test
+// suite failing on a purely cosmetic difference.
+//
+// A QUERY parameter and a COOKIE name are case-SENSITIVE, so those go in
+// verbatim: `?token=` is not `?Token=`.
+function credLiteral(where: string, name: string): string {
+  return 'header' === where ? String(name).toLowerCase() : String(name)
+}
+
+
+// The bag the credential lands in, per placement. Cookies ride the header
+// bag because a cookie IS a header.
+function bagName(where: string): string {
+  return 'query' === where ? 'query' : 'headers'
+}
+
+
+function bagField(where: string): string {
+  return 'query' === where ? 'Query' : 'Headers'
+}
+
+
+function clear(where: string): string {
+  return `delete(${bagName(where)}, credName)`
+}
+
+
+function place(where: string): string {
+  if ('query' === where) {
+    // 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.
+    return `		apikeyVal := ""
+		if av, ok := apikey.(string); ok {
+			apikeyVal = av
+		}
+		query[credName] = apikeyVal`
+  }
+
+  if ('cookie' === where) {
+    // Append, never replace: the cookie header may already carry pairs this
+    // SDK did not set, and clobbering it would drop them.
+    return `		apikeyVal := ""
+		if av, ok := apikey.(string); ok {
+			apikeyVal = av
+		}
+		pair := credName + "=" + apikeyVal
+		existing := ""
+		if ec, ok := headers[cookieHeader].(string); ok {
+			existing = ec
+		}
+		if existing == "" {
+			headers[cookieHeader] = pair
+		} else {
+			headers[cookieHeader] = existing + "; " + pair
+		}`
+  }
+
+  return `		authPrefix := ""
+		if ap := vs.GetPath(options, []any{"auth", "prefix"}); ap != nil {
+			authPrefix, _ = ap.(string)
+		}
+		apikeyVal := ""
+		if av, ok := apikey.(string); ok {
+			apikeyVal = av
+		}
+		// Empty prefix (raw apiKey credential) must not add a leading space.
+		if authPrefix == "" {
+			headers[credName] = apikeyVal
+		} else {
+			headers[credName] = authPrefix + " " + apikeyVal
+		}`
+}
+
+
+function gostr(s: string): string {
+  return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
+
+
+export {
+  PrepareAuth
+}
+
+
+// NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING. That helper is
+// also false whenever the SPEC declares no security scheme
+// (`main.kit.info.auth: false`) — a statement about the DEFINITION, not a
+// ban on ever sending a credential. `optspec` still declares `apikey` and
+// makeOptions fills `options.auth` from its defaults, so the runtime
+// `options.auth == null` guard never fired and those SDKs have always sent
+// the credential. Gating the body on `isAuthActive` does not trim dead
+// code, it removes working authentication — which
+// `go: auth null suppresses the credential` catches, and which takes the
+// secrets feature down with it.
+//
+// `main.kit.config.auth.active: false` is the project saying "no credential,
+// ever", and it is the only signal that can be honoured before runtime.
+function isAuthActive_go(model: any): boolean {
+  const auth = getModelPath(model, `main.${KIT}.config.auth`,
+    { only_active: false, required: false })
+  return !(null != auth && false === auth.active)
+}

package/project/.sdk/src/cmp/go/Schema_go.ts

@@ -0,0 +1,93 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+import {
+  formatGoString,
+} from './utility_go'
+
+
+// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
+//
+// The go 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 — both built by the shared
+// helpers, so what go validates against and what ts validates against cannot
+// drift.
+//
+// EMBEDDED AS JSON, PARSED AT LOAD, where ts emits an object literal. JSON is
+// a subset of TypeScript's own literal syntax and is not a subset of go's, so
+// the literal ts writes directly is a `map[string]any{...}` tree here — which
+// this could render (utility_go has the formatter config.go's literal branch
+// uses), but the JSON string is the smaller, simpler artefact and every
+// target this is being ported to already carries one for its config.
+//
+// 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. That is not incidental. json.Unmarshal decodes
+// EVERY JSON number as float64, and struct reads a spec by example, so one
+// number in here would mean something different in go than in ts — the same
+// disagreement configNormalise exists to repair in config.go.
+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(`package core
+
+import (
+	"encoding/json"
+)
+
+// ${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.
+
+const optspecJSON = ${formatGoString(JSON.stringify(optspec))}
+
+const entityspecJSON = ${formatGoString(JSON.stringify(entityspec))}
+
+// Parsed ONCE, at package init. The spec is read on every client
+// construction and never mutated, so a per-call parse would be pure waste —
+// and a shared map is safe here for the same reason the spec is a constant:
+// MakeOptions validates AGAINST it and writes into the options, never into
+// the spec.
+var (
+	OPTSPEC    = mustSpec(optspecJSON)
+	ENTITYSPEC = mustSpec(entityspecJSON)
+)
+
+func mustSpec(src string) map[string]any {
+	var out map[string]any
+	if err := json.Unmarshal([]byte(src), &out); err != nil {
+		// Unreachable: generated by json.Marshal's counterpart and never
+		// edited by hand. Panic rather than hand back an empty spec, which
+		// would validate everything and fail far from the cause.
+		panic("${model.const.Name}: embedded schema is not valid JSON: " + err.Error())
+	}
+	return out
+}
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/java/Config_java.ts

@@ -6,6 +6,9 @@ import {
   configDefinition,
   each,
   isAuthActive,
+  isHttpBasicAuth,
+  resolveAuthIn,
+  resolveAuthName,
   resolveAuthPrefix,
   targetFeatures,
 } from '@voxgig/sdkgen'
@@ -53,6 +56,14 @@ const Config = cmp(async function Config(props: any) {
   const authActive = isAuthActive(model)
   // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
   const authPrefix = resolveAuthPrefix(model)
+  const authBasic = isHttpBasicAuth(model)
+  // `in` and `name` travel with the prefix now. They were resolved by
+  // apidef all along and dropped here, so an apiKey-in-query API got an
+  // Authorization header it does not read. Emitted only when they differ
+  // from the defaults, so a header/Authorization SDK is byte-identical to
+  // what it generated before.
+  const authIn = resolveAuthIn(model)
+  const authName = resolveAuthName(model)
 
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
@@ -174,7 +185,15 @@ const Config = cmp(async function Config(props: any) {
   }
 
   if (authActive) {
-    options.auth = { prefix: authPrefix }
+    const auth: Record<string, any> = { prefix: authPrefix }
+    // `basic` joins it for the same reason: the generated prepareAuth only
+    // emits the base64(user:pass) branch for a spec-declared HTTP Basic
+    // scheme, and that branch reads this option at runtime — without it the
+    // branch could never fire.
+    if (authBasic) { auth.basic = true }
+    if ('header' !== authIn) { auth.in = authIn }
+    if ('Authorization' !== authName) { auth.name = authName }
+    options.auth = auth
   }
   options.headers = headers
   options.entity = optionsEntity

package/project/.sdk/src/cmp/java/Main_java.ts

@@ -23,11 +23,13 @@ import {
 
 import { Package } from './Package_java'
 import { Config } from './Config_java'
+import { Schema } from './Schema_java'
 import { Gitignore } from './Gitignore_java'
 import { MainEntity } from './MainEntity_java'
 import { EntityBase } from './EntityBase_java'
 import { EntityTypes } from './EntityTypes_java'
 import { SdkError } from './SdkError_java'
+import { PrepareAuth } from './PrepareAuth_java'
 import { javaPackage } from './utility_java'
 
 
@@ -72,6 +74,19 @@ const Main = cmp(async function Main(props: any) {
   // Shared entity runtime (entity/EntityBase.java).
   EntityBase({ target })
 
+  // utility/PrepareAuth.java. WHERE the credential goes (header, query
+  // parameter or cookie) and UNDER WHAT NAME are facts about the API, so
+  // the file is generated from the model rather than copied from tm/ —
+  // which is why tm/java/utility/PrepareAuth.java was deleted: the blanket
+  // Copy above and this component would otherwise both claim that path and
+  // jostraca refuses a duplicate output path.
+  //
+  // Called HERE, at Main's top level, and NOT inside the `core` Folder
+  // below. The java target is flat — utility/ is a SIBLING of core/, not a
+  // child — and the component opens `utility` itself, exactly as
+  // EntityBase opens `entity`.
+  PrepareAuth({ target })
+
   // Generate the client class and config in core/.
   Folder({ name: 'core' }, () => {
 
@@ -105,6 +120,7 @@ this.utility.featureHook.apply(this.rootctx, "${name}");
     })
 
     Config({ target })
+    Schema({ target })
 
     // Generate the typed reference-model file (<Name>Types.java) beside the
     // other generated core files. Documentation/DX shapes only — not wired