@voxgig/sdkgen 4.19.1 → 4.21.0

package/project/.sdk/src/cmp/csharp/PrepareAuth_csharp.ts

@@ -0,0 +1,392 @@
+
+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/csharp/utility/PrepareAuth.cs` that
+// hardcoded `authorization` and a header. 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.
+//
+// This is the csharp port of PrepareAuth_ts, and it keeps the C# file's
+// own idioms (lazy prefix read, `TryGetValue` for a suppressed auth
+// block, `Remove` rather than a struct delprop): the credential MOVES,
+// nothing else changes. For the default header placement the rendered
+// file is BYTE-IDENTICAL to the template it replaces, so every
+// header-based csharp SDK regenerates with no diff at all.
+const PrepareAuth = cmp(async function PrepareAuth(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const active = !authSwitchedOff(model)
+  const where = resolveAuthIn(model)
+  const name = resolveAuthName(model)
+  const basic = isHttpBasicAuth(model)
+
+  // `utility`, opened HERE, and the call site in Main_csharp is at the
+  // ROOT - deliberately outside `Folder({ name: 'core' })`.
+  //
+  // csharp's layout is not ts's. Main_csharp copies `tm/csharp` at the
+  // root, so the template this replaces landed at `<out>/utility/
+  // PrepareAuth.cs`, beside MakeSpec.cs and Register.cs - which is the
+  // one path that compiles, since Register.cs wires `u.PrepareAuth =
+  // PrepareAuthUtil` from the same `partial class SdkUtility`. The
+  // generated files (Config, SdkError, EntityBase, EntityTypes) sit one
+  // level down in `core/` because Main opens that Folder around them; a
+  // call from inside it would write `core/utility/PrepareAuth.cs`, which
+  // nothing compiles into the utility partial and which would leave the
+  // stale copy at `utility/` being used instead.
+  Folder({ name: 'utility' }, () => {
+    File({ name: 'PrepareAuth.' + target.ext }, () => {
+      Content(render({
+        Name: model.const.Name,
+        active,
+        where,
+        name,
+        basic,
+      }))
+    })
+  })
+})
+
+
+// DELIBERATELY NARROWER THAN isAuthActive, and measured rather than assumed.
+//
+// isAuthActive answers TWO different questions with one boolean:
+//
+//   1. `main.kit.config.auth.active: false` - this SDK is deliberately
+//      built WITHOUT auth. A per-SDK decision.
+//   2. `main.kit.info.auth: false`          - the SPEC declares no security
+//      scheme. A fact about the API.
+//
+// Only (1) may silence prepareAuth. (2) says nothing about whether the
+// CALLER holds a credential, and csharp has always let one through: the
+// optspec in tm/csharp/utility/MakeOptions.cs supplies an `auth` default
+// map whether or not the generated config carries one, so `options.auth` is
+// non-null at runtime and the old template placed `options.apikey` in the
+// authorization header regardless of what the spec declared. The generated
+// secrets feature and the auth-null probe both depend on exactly that.
+//
+// Gating the no-op on isAuthActive instead turns two csharp tests red -
+// `csharp: auth null beats an explicit apikey` ("baseline broken: an
+// ordinary apikey was not sent") and `csharp: the secrets feature runs with
+// the feature active` - because the generate harness model IS case (2)
+// (`main: kit: info: { ..., auth: false }`). Losing the ability to
+// authenticate is the defect this whole change exists to fix, so it is not
+// worth re-introducing at the other end.
+function authSwitchedOff(model: any): boolean {
+  const auth = getModelPath(model, `main.${KIT}.config.auth`,
+    { only_active: false, required: false })
+  return null != auth && false === auth.active
+}
+
+
+function render(spec: {
+  Name: string, active: boolean, where: string, name: string, basic: boolean
+}): string {
+  const Name = spec.Name
+
+  // AUTH SWITCHED OFF FOR THIS SDK (`config.auth.active: false`). The
+  // project has said it wants no credential placed, so prepareAuth places
+  // none - rather than one that deletes a header nobody set.
+  if (!spec.active) {
+    return `// ${Name} SDK utility: prepareAuth - this SDK is built with auth
+// switched off, so there is no credential to place.
+
+namespace ${Name}Sdk.Util;
+
+public static partial class SdkUtility
+{
+    // Still in the pipeline: MakeSpec calls PrepareAuth unconditionally, and
+    // a missing spec is still the same error it always was.
+    internal static Spec PrepareAuthUtil(Context ctx)
+    {
+        return ctx.Spec ?? throw ctx.MakeError("auth_no_spec",
+            "Expected context spec property to be defined.");
+    }
+}
+`
+  }
+
+  if ('query' === spec.where) {
+    return renderQuery(Name, csstr(spec.name))
+  }
+
+  if ('cookie' === spec.where) {
+    return renderCookie(Name, csstr(spec.name))
+  }
+
+  // HEADER NAMES ARE LOWERCASED, and the rest of the generated C# is why.
+  // `spec.Headers` is a plain Dictionary<string, object?> - case-SENSITIVE -
+  // and every other writer of an auth header in this target spells it
+  // lowercase: SecretsFeature re-writes `headers["authorization"]` on a
+  // refresh, MakeSpec sets `headers["content-type"]`, and the generated
+  // tests assert `Headers["authorization"]`. An `Authorization` key here
+  // would sit BESIDE those rather than replace them and go out as a second
+  // header. Header names are case-insensitive on the wire (RFC 7230) and
+  // lowercase on HTTP/2, so nothing is lost. Query parameter and cookie
+  // names, which ARE case-sensitive, are emitted verbatim above.
+  return renderHeader(Name, csstr(String(spec.name).toLowerCase()), spec.basic)
+}
+
+
+// HEADER. Byte-identical to the template it replaces whenever the resolved
+// name is the default (`authorization`) and the scheme is not HTTP Basic.
+function renderHeader(Name: string, cred: string, basic: boolean): string {
+  // 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 here, and
+  // only when the model says this API actually uses it - a bearer SDK
+  // carries none of it.
+  const basicConst = basic ? `
+    private const string OptionSecret = "secret";` : ''
+
+  const basicBlock = basic ? `
+        // 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 (StructUtils.GetPath(options, StructUtils.Jt("auth", "basic")) is bool isBasic &&
+            isBasic)
+        {
+            var secret = StructUtils.GetProp(options, OptionSecret, NotFound);
+
+            var noApikey = apikey == null ||
+                (apikey is string akStr && (akStr == NotFound || akStr == ""));
+            var noSecret = secret == null ||
+                (secret is string skStr && (skStr == NotFound || skStr == ""));
+
+            if (noApikey || noSecret)
+            {
+                headers.Remove(HeaderAuth);
+            }
+            else
+            {
+                var basicPrefix = "";
+                if (StructUtils.GetPath(options, StructUtils.Jt("auth", "prefix")) is string bp)
+                {
+                    basicPrefix = bp;
+                }
+                var b64 = Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(
+                    (apikey as string ?? "") + ":" + (secret as string ?? "")));
+                headers[HeaderAuth] = basicPrefix == ""
+                    ? b64
+                    : basicPrefix + " " + b64;
+            }
+
+            return spec;
+        }
+` : ''
+
+  return `// ${Name} SDK utility: prepareAuth - shape the ${cred} header
+// from the client options.
+
+using Voxgig.Struct;
+
+namespace ${Name}Sdk.Util;
+
+public static partial class SdkUtility
+{
+    private const string HeaderAuth = "${cred}";
+    private const string OptionApikey = "apikey";${basicConst}
+    private const string NotFound = "__NOTFOUND__";
+
+    internal static Spec PrepareAuthUtil(Context ctx)
+    {
+        var spec = ctx.Spec ?? throw ctx.MakeError("auth_no_spec",
+            "Expected context spec property to be defined.");
+
+        var headers = spec.Headers;
+        var options = ctx.Client!.OptionsMap();
+
+        // Public APIs that need no auth omit the options.auth block entirely.
+        if (!options.TryGetValue("auth", out var auth) || auth == null)
+        {
+            headers.Remove(HeaderAuth);
+            return spec;
+        }
+
+        var apikey = StructUtils.GetProp(options, OptionApikey, NotFound);
+${basicBlock}
+        var skip = apikey == null ||
+            (apikey is string apikeyStr && (apikeyStr == NotFound || apikeyStr == ""));
+
+        if (skip)
+        {
+            headers.Remove(HeaderAuth);
+        }
+        else
+        {
+            var authPrefix = "";
+            if (StructUtils.GetPath(options, StructUtils.Jt("auth", "prefix")) is string ap)
+            {
+                authPrefix = ap;
+            }
+            var apikeyVal = apikey as string ?? "";
+            // Empty prefix (raw apiKey credential) must not add a leading space.
+            headers[HeaderAuth] = authPrefix == ""
+                ? apikeyVal
+                : authPrefix + " " + apikeyVal;
+        }
+
+        return spec;
+    }
+}
+`
+}
+
+
+// QUERY. MakeSpec fills spec.Query before it calls PrepareAuth, and MakeUrl
+// reads spec.Query afterwards (via MakeFetchDef), url-escaping every key and
+// value - so the credential placed here reaches the wire as `?name=value`.
+function renderQuery(Name: string, cred: string): string {
+  return `// ${Name} SDK utility: prepareAuth - carry the API credential in the
+// ${cred} query parameter, from the client options.
+
+using Voxgig.Struct;
+
+namespace ${Name}Sdk.Util;
+
+public static partial class SdkUtility
+{
+    private const string QueryAuth = "${cred}";
+    private const string OptionApikey = "apikey";
+    private const string NotFound = "__NOTFOUND__";
+
+    internal static Spec PrepareAuthUtil(Context ctx)
+    {
+        var spec = ctx.Spec ?? throw ctx.MakeError("auth_no_spec",
+            "Expected context spec property to be defined.");
+
+        var query = spec.Query;
+        var options = ctx.Client!.OptionsMap();
+
+        // Public APIs that need no auth omit the options.auth block entirely.
+        if (!options.TryGetValue("auth", out var auth) || auth == null)
+        {
+            query.Remove(QueryAuth);
+            return spec;
+        }
+
+        var apikey = StructUtils.GetProp(options, OptionApikey, NotFound);
+
+        var skip = apikey == null ||
+            (apikey is string apikeyStr && (apikeyStr == NotFound || apikeyStr == ""));
+
+        if (skip)
+        {
+            query.Remove(QueryAuth);
+        }
+        else
+        {
+            var apikeyVal = apikey as string ?? "";
+            // NO PREFIX IN A QUERY STRING. \`?token=Bearer%20abc\` is not a thing
+            // any API reads; the prefix is a header convention, so
+            // options.auth.prefix is dropped here deliberately rather than
+            // silently concatenated.
+            query[QueryAuth] = apikeyVal;
+        }
+
+        return spec;
+    }
+}
+`
+}
+
+
+// COOKIE. A cookie IS a header, so the credential rides in the shared
+// `cookie` header - APPENDED to whatever options.headers (or an earlier
+// feature) already put there, never assigned over it.
+function renderCookie(Name: string, cred: string): string {
+  return `// ${Name} SDK utility: prepareAuth - carry the API credential in the
+// ${cred} cookie, from the client options.
+
+using Voxgig.Struct;
+
+namespace ${Name}Sdk.Util;
+
+public static partial class SdkUtility
+{
+    private const string CookieAuth = "${cred}";
+    private const string HeaderCookie = "cookie";
+    private const string OptionApikey = "apikey";
+    private const string NotFound = "__NOTFOUND__";
+
+    internal static Spec PrepareAuthUtil(Context ctx)
+    {
+        var spec = ctx.Spec ?? throw ctx.MakeError("auth_no_spec",
+            "Expected context spec property to be defined.");
+
+        var headers = spec.Headers;
+        var options = ctx.Client!.OptionsMap();
+
+        // Public APIs that need no auth omit the options.auth block entirely.
+        if (!options.TryGetValue("auth", out var auth) || auth == null)
+        {
+            // Nothing of ours to remove: the credential rides INSIDE the
+            // shared cookie header, which this function only ever appends to.
+            // Returning here is what withholds it.
+            return spec;
+        }
+
+        var apikey = StructUtils.GetProp(options, OptionApikey, NotFound);
+
+        var skip = apikey == null ||
+            (apikey is string apikeyStr && (apikeyStr == NotFound || apikeyStr == ""));
+
+        if (!skip)
+        {
+            var apikeyVal = apikey as string ?? "";
+            // Append, never assign: a cookie header set by options.headers
+            // would otherwise be clobbered by the credential. No prefix - a
+            // cookie value is the credential itself.
+            var existing = StructUtils.GetProp(headers, HeaderCookie, "") as string ?? "";
+            var pair = CookieAuth + "=" + apikeyVal;
+            headers[HeaderCookie] = existing == ""
+                ? pair
+                : existing + "; " + pair;
+        }
+
+        return spec;
+    }
+}
+`
+}
+
+
+// A C# double-quoted string literal body. These names come from the API's
+// own securityScheme, so they are not guaranteed to be bare identifiers.
+function csstr(s: string): string {
+  return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
+
+
+export {
+  PrepareAuth
+}

package/project/.sdk/src/cmp/csharp/Schema_csharp.ts

@@ -0,0 +1,85 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+import {
+  formatCsMap,
+} from './utility_csharp'
+
+
+// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
+//
+// The csharp peer of src/cmp/ts/Schema_ts.ts. Same two members, 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 csharp validates against and what ts validates against
+// cannot drift.
+//
+// A COLLECTION LITERAL, not embedded JSON, where go and the JVM targets
+// parse a string. SdkConfig switches to a JSON constant above a size
+// threshold because a large composite literal is slow for the compiler to
+// bind and the JIT to run; the spec has no such spread. It is bounded by the
+// option list and the feature set — a few hundred entries whatever the API
+// looks like — and in C# the literal is also the SAFER rep: a `false` here
+// stays `false` rather than arriving as a JsonElement to be mapped back, and
+// the number ladder SdkConfig's ConfigValue exists to reproduce is a question
+// the spec never asks (it holds only strings and booleans, pinned by "strings
+// and booleans only" 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) || {}
+
+  // Beside Config.cs, and for the same reason: core owns the generated data,
+  // so nothing in the copied runtime has to reach up for it.
+  File({ name: 'Schema.' + target.ext }, () => {
+
+    Content(`// ${model.const.Name} SDK - generated schemas. GENERATED from the API model -
+// do not edit by hand.
+//
+// Built from the model: \`main.kit.optspec\` and each feature's
+// \`config.options\` for Optspec; entity \`fields[].type\` for Entityspec.
+
+namespace ${model.const.Name}Sdk;
+
+public static class SdkSchema
+{
+    // Built ONCE, on first use. The spec is read on every client construction
+    // and never mutated, so rebuilding it per call would be pure waste — and
+    // a shared dictionary is safe for the same reason the spec is a constant:
+    // MakeOptions validates AGAINST it and writes into the options, never
+    // into the spec.
+    //
+    // A static field initializer, so the CLR's type initializer gives the
+    // once-only, thread-safe guarantee with no locking on the read path.
+
+    /// <summary>The option spec MakeOptions validates client options against.</summary>
+    public static readonly Dictionary<string, object?> Optspec =
+        ${formatCsMap(optspec, 2)};
+
+    /// <summary>Per-entity data and request specs, keyed by entity name.</summary>
+    public static readonly Dictionary<string, object?> Entityspec =
+        ${formatCsMap(entityspec, 2)};
+}
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/elixir/Config_elixir.ts

@@ -9,6 +9,8 @@ import {
   each,
   isAuthActive,
   isConfigData,
+  resolveAuthIn,
+  resolveAuthName,
   resolveAuthPrefix,
   targetFeatures,
 } from '@voxgig/sdkgen'
@@ -44,6 +46,14 @@ const Config = cmp(async function Config(props: any) {
 
   const authActive = isAuthActive(model)
   const authPrefix = resolveAuthPrefix(model)
+  // `in` and `name` travel with the prefix now. apidef resolved both from
+  // the spec's securityScheme all along (joplin's says `in: "query",
+  // name: "token"`) and generation dropped them, so an apiKey-in-query API
+  // got an Authorization header it does not read. Emitted below ONLY when
+  // they differ from the header/Authorization defaults, so a header SDK's
+  // config.ex 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) { }
@@ -127,7 +137,32 @@ const Config = cmp(async function Config(props: any) {
     // 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: configDef, json: configJson } = configDefinition(model, target.name)
+    const { def: configDef } = configDefinition(model, target.name)
+
+    // THE PLACEMENT, ONTO THE CANONICAL DEFINITION RATHER THAN INTO ONE
+    // BRANCH. Both reps below render from `configDef` - the literal through
+    // formatElixir, the data through JSON - so overlaying the fact here is
+    // what keeps them the same config either side of the threshold. (Targets
+    // whose literal is a hand-assembled fragment had to emit the block twice
+    // and only did it once; elixir renders `options` whole, so it cannot
+    // drift.)
+    //
+    // The optspec in utility.ex's make_options declares `in` and `name` for
+    // exactly this reason: this port's validate REJECTS a key the spec does
+    // not list, so a config carrying a placement the optspec has never heard
+    // of does not degrade quietly - the client cannot be constructed at all
+    // (`** (Voxgig.Struct.Error) Unexpected keys at field auth: in, name`,
+    // measured by removing the optspec entry from a generated query SDK).
+    if (authActive && null != configDef.options && null != configDef.options.auth) {
+      if ('header' !== authIn) configDef.options.auth.in = authIn
+      if ('Authorization' !== authName) configDef.options.auth.name = authName
+    }
+
+    // Re-stringified AFTER the overlay, so the size the threshold is measured
+    // on is the size of the config actually emitted. For a header SDK the
+    // overlay adds nothing and this is byte-identical to configDefinition's
+    // own json.
+    const configJson = JSON.stringify(configDef)
     const asData = isConfigData(configJson, configReprSetting(model))
 
     // configDefinition's `def.entity` verbatim, NOT rebuilt here. The reduce

package/project/.sdk/src/cmp/elixir/Main_elixir.ts

@@ -17,6 +17,8 @@ import {
 
 import { Package } from './Package_elixir'
 import { Config } from './Config_elixir'
+import { Schema } from './Schema_elixir'
+import { PrepareAuth } from './PrepareAuth_elixir'
 import { Gitignore } from './Gitignore_elixir'
 import { MainEntity } from './MainEntity_elixir'
 import { EntityTypes } from './EntityTypes_elixir'
@@ -155,10 +157,25 @@ defmodule ${Name}.Features do
 end
 `)
     })
+
+    // WHERE THE CREDENTIAL GOES IS GENERATED, NOT COPIED. prepare_auth was
+    // the one pipeline utility whose answer is a fact about the API rather
+    // than about the language, and tm/ can only hold one answer - so it is
+    // extracted out of the copied utility.ex into its own module here. See
+    // PrepareAuth_elixir for the extraction and for why the registration in
+    // utility.ex still binds it.
+    //
+    // CALLED FROM INSIDE THIS `lib` FOLDER, and the component opens only
+    // `<name>`, so the file lands at lib/<name>/prepare_auth.ex - beside the
+    // utility.ex the Copy above puts at lib/<name>/utility.ex. Opening `lib`
+    // in the component too would write lib/lib/<name>/, which mix would
+    // compile anyway (it globs the whole tree) and no test could see.
+    PrepareAuth({ target })
   })
 
   // Config module.
   Config({ target })
+  Schema({ target })
 })