@voxgig/sdkgen 3.4.7 → 3.5.0

package/project/.sdk/src/cmp/dart/fragment/Config.data.fragment.dart

@@ -0,0 +1,74 @@
+import 'dart:convert';
+
+import 'feature/base/BaseFeature.dart';
+// #ImportFeatures
+
+// ignore: non_constant_identifier_names
+final Map<String, BaseFeature Function()> FEATURE_CLASS = {
+  // #FeatureClasses
+};
+
+// THE API MODEL, EMBEDDED AS DATA (sdkgen rung L1).
+//
+// The literal form of this file declares the whole model as nested map
+// literals. For a large API that is megabytes of source the Dart analyzer and
+// compiler must parse and type every node of, on every build, and that the VM
+// must build entry by entry on every load.
+//
+// As a single string constant it is one token, and `jsonDecode` builds the map
+// far faster than the equivalent literal.
+//
+// Emitted only above a size threshold, or when `main.kit.config.repr` pins it:
+// for a small model the literal is smaller, loads no slower, and is far easier
+// to read when debugging.
+const String _CONFIG_DATA = 'CONFIGJSON';
+
+class Config {
+  // ONE decode per constructed Config, and each instance owns the maps it
+  // decoded. The literal representation builds fresh maps in every field
+  // initialiser, so a caller that constructs a second Config and mutates it
+  // does not touch the first - and `Config` is exported by Main.fragment.dart,
+  // so callers really can construct one.
+  //
+  // Sharing a single top-level parsed map would have been cheaper and was the
+  // first attempt; it made `Config().options['x'] = 1` mutate the `config`
+  // singleton every SDK client reads. Decoding per instance costs about what
+  // building the literal per instance cost, and the rung's win is untouched:
+  // L1 is about what the COMPILER has to walk, not what happens at load.
+  Config() : this._(jsonDecode(_CONFIG_DATA) as Map<String, dynamic>);
+
+  Config._(Map<String, dynamic> data)
+      : main = data['main'] as Map<String, dynamic>,
+        feature = data['feature'] as Map<String, dynamic>,
+        options = data['options'] as Map<String, dynamic>,
+        entity = data['entity'] as Map<String, dynamic>;
+
+  BaseFeature makeFeature(String fn) {
+    final fc = FEATURE_CLASS[fn];
+    if (null == fc) {
+      // TODO: errors etc
+      throw StateError('Unknown feature: ' + fn);
+    }
+    return fc();
+  }
+
+  // The same fields the literal declares - same names, same types, same
+  // finalness - so callers cannot tell which representation they were given.
+  final Map<String, dynamic> main;
+
+  final Map<String, dynamic> feature;
+
+  final Map<String, dynamic> options;
+
+  final Map<String, dynamic> entity;
+
+  // The pipeline context carries the config as a plain map.
+  Map<String, dynamic> toMap() => <String, dynamic>{
+        'main': main,
+        'feature': feature,
+        'options': options,
+        'entity': entity,
+      };
+}
+
+final config = Config();

package/project/.sdk/src/cmp/dart/fragment/Config.fragment.dart

@@ -24,15 +24,12 @@ class Config {
     // #FeatureConfigs
   };
 
-  final Map<String, dynamic> options = <String, dynamic>{
-    'base': 'BASEURL',
-
-    'AUTHBLOCK''headers': 'HEADERS',
-
-    'entity': <String, dynamic>{
-      // #EntityConfigs
-    }
-  };
+  // Rendered whole from the canonical config definition rather than assembled
+  // slot by slot. Assembling it here meant `options.server` - the OpenAPI
+  // server-variable defaults - was simply absent from this branch, so a
+  // templated server URL produced a different config either side of the
+  // threshold.
+  final Map<String, dynamic> options = 'OPTIONSMAP';
 
   final Map<String, dynamic> entity = 'ENTITYMAP';
 

package/project/.sdk/src/cmp/dart/fragment/Main.fragment.dart

@@ -9,20 +9,31 @@ import 'Spec.dart';
 // a Dart `export` needs no matching `import`, so importing them here too is an
 // unused_import. Keep only the imports actually referenced in this file.
 import 'utility/ErrUtility.dart';
-import 'utility/Utility.dart';
+// PREFIXED, and deliberately not re-exported. The runtime helper class is
+// named `Utility`, and so is the generated data class for an entity named
+// `utility` (ProjectNameTypes.dart) — exporting both from this library makes
+// the name ambiguous and NO dart SDK for such an API compiles:
+//
+//   Error: 'Utility' is exported from both 'lib/ProjectNameTypes.dart'
+//          and 'lib/utility/Utility.dart'
+//
+// The entity type is the user-facing name, so it keeps the plain one; the
+// runtime helper is internal plumbing and is reached through the prefix. Any
+// entity name can collide with an internal class, so the prefix — not a
+// rename — is what makes this safe for every API.
+import 'utility/Utility.dart' as sdkutil;
 
 export 'Config.dart' show Config, config;
 export 'ProjectNameEntityBase.dart' show ProjectNameEntityBase;
 export 'ProjectNameError.dart' show ProjectNameError;
 export 'feature/base/BaseFeature.dart' show BaseFeature;
-export 'utility/Utility.dart' show Utility;
 
-final Utility stdutil = Utility();
+final sdkutil.Utility stdutil = sdkutil.Utility();
 
 class ProjectNameSDK {
   String mode = 'live';
   dynamic _options;
-  final Utility _utility = Utility();
+  final sdkutil.Utility _utility = sdkutil.Utility();
   List<dynamic> features = [];
   dynamic rootctx;
 
@@ -85,7 +96,7 @@ class ProjectNameSDK {
     return _utility.struct.clone(_options);
   }
 
-  Utility utility() {
+  sdkutil.Utility utility() {
     return _utility;
   }
 

package/project/.sdk/src/cmp/dart/utility_dart.ts

@@ -129,7 +129,25 @@ function clean(o: any, dropDefaults?: boolean): any {
 }
 
 
+
+// The JSON as a Dart string literal.
+//
+// Dart's ordinary string literals INTERPOLATE: `$name` and `${...}` are
+// substitution, and the model is full of `$` - `$STRING`, `$NUMBER`,
+// `$action`. A raw string (`r'...'`) would avoid that but cannot contain its
+// own quote character and has no escape for it, and the JSON contains both
+// quote characters in quantity.
+//
+// So: JSON.stringify's escaping, which already handles `"` and `\` and emits
+// no raw control characters, plus `$` -> `\$`. That last step is unambiguous
+// precisely because JSON.stringify has already escaped every backslash, so a
+// `\$` here can only have come from this rule.
+function dartStringLiteral(json: string): string {
+  return JSON.stringify(json).replace(/\$/g, '\\$')
+}
+
 export {
+  dartStringLiteral,
   clean,
   dartString,
   dartValue,

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

@@ -4,8 +4,11 @@ import {
   File,
   Folder,
   cmp,
+  configDefinition,
+  configReprSetting,
   each,
   isAuthActive,
+  isConfigData,
   resolveAuthPrefix,
 } from '@voxgig/sdkgen'
 
@@ -53,8 +56,101 @@ const Config = cmp(async function Config(props: any) {
   }, true), a), {})
 
   Folder({ name: 'lib' }, () => {
+    // The same config as an OBJECT, built by the shared helper so this
+    // target's literal and the data that replaces it above the threshold are
+    // the same config by construction. The JSON is what the threshold is
+    // measured on - emitted source size varies by language, the model does not.
+    const { def: configDef, json: configJson } = configDefinition(model)
+    const asData = isConfigData(configJson, configReprSetting(model))
+
     File({ name: 'config.ex' }, () => {
 
+      // ABOVE THE THRESHOLD: emit the model as DATA.
+      //
+      // The literal is one nested `%{}` the Elixir compiler expands and holds
+      // in the module's constant pool; a binary is one token. `Json.parse`
+      // builds the vendored struct's heap nodes DIRECTLY - the same nodes
+      // `Helpers.deep/1` produces from a plain map - so make_config returns
+      // exactly what it returned before.
+      //
+      // `ProjectName.Json` is already the SDK's response decoder (see
+      // `safe_json` in utility.ex), so this adds no dependency.
+      if (asData) {
+        Content(`# ${Name} SDK configuration
+#
+# THE API MODEL, EMBEDDED AS DATA (sdkgen rung L1).
+#
+# Emitted only above a size threshold, or when \`main.kit.config.repr\` pins
+# it: for a small model the literal is smaller and far easier to read when
+# debugging. Do not edit by hand.
+
+defmodule ${Name}.Config do
+  @config_data ${elixirString(configJson)}
+
+  def make_config do
+    ${Name}.Json.parse(@config_data)
+  end
+
+  # SHARED CONFIG (sdkgen rung L2).
+  #
+  # The SDK reads the config on every request and never writes to it, so one
+  # instance is shared by every client rather than rebuilt per client. Above the
+  # size threshold make_config re-parses the whole embedded JSON, so this is the
+  # difference between parsing the model once and once per client.
+  #
+  # :persistent_term because struct nodes are ETS-backed handles: the stored
+  # value is the handle, so every caller gets the same nodes. A concurrent first
+  # call may build twice and the last write wins - both results are valid
+  # configs, so the race is benign.
+  @shared_key {__MODULE__, :shared_config}
+
+  # The process-wide config, built once on first use.
+  #
+  # The returned node is SHARED: treat it as read-only. Callers that need to
+  # mutate should use make_config, which always returns a fresh copy.
+  #
+  # VALIDATED ON READ, and this is not belt-and-braces. The struct heap is a
+  # named ETS table created with no heir, so it is owned by whichever process
+  # first touched struct. If that was a short-lived one - a Task, a request, an
+  # ExUnit case - the table dies with it and every handle allocated in it goes
+  # stale. Caching a handle in :persistent_term makes that permanent: without
+  # this check the SDK hands out the dead handle for the life of the VM and
+  # every getprop raises ArgumentError. Reproduced:
+  #
+  #     cached inside a task: {:vmap, 144}
+  #     heap alive after task exit: :undefined
+  #     getprop RAISED: ArgumentError
+  #
+  # Rebuilding on a dead handle costs one parse and restores exactly the
+  # pre-L2 behaviour, so the failure degrades to "no sharing" rather than to a
+  # broken SDK. The real fix is a durable owner for the heap, which belongs in
+  # the struct port rather than here.
+  def shared_config do
+    cached = :persistent_term.get(@shared_key, nil)
+
+    if cached != nil and usable?(cached) do
+      cached
+    else
+      cfg = make_config()
+      :persistent_term.put(@shared_key, cfg)
+      cfg
+    end
+  end
+
+  # Is this handle still backed by a live heap? Asked through the public API
+  # rather than by inspecting the table, so it stays correct if struct changes
+  # how nodes are stored.
+  defp usable?(cfg) do
+    Voxgig.Struct.getprop(cfg, "main")
+    true
+  rescue
+    ArgumentError -> false
+  end
+end
+`)
+        return
+      }
+
       Content(`# ${Name} SDK configuration
 #
 # Returns the resolved SDK config as vendored-struct nodes (via
@@ -72,23 +168,42 @@ defmodule ${Name}.Config do
 `)
       })
 
+      // `options` rendered WHOLE from the canonical definition rather than
+      // assembled slot by slot. Assembling it meant `options.server` - the
+      // OpenAPI server-variable defaults - was simply absent from this branch,
+      // so a templated server URL described a different config either side of
+      // the threshold. Same fix as dart, rust and zig.
       Content(`      },
-      "options" => %{
-        "base" => ${elixirString(baseUrl)},
-${authBlock}        "headers" => ${formatElixir(headers, 4)},
-        "entity" => %{
-`)
-
-      each(entity, (e: any) => {
-        Content(`          ${elixirString(e.name)} => %{},
-`)
-      })
-
-      Content(`        }
-      },
+      "options" => ${formatElixir(configDef.options, 3)},
       "entity" => ${formatElixir(entityClean, 3)}
     })
   end
+
+  # SHARED CONFIG (sdkgen rung L2). See the data branch for the rationale, and
+  # for why the cached handle is validated on read.
+  @shared_key {__MODULE__, :shared_config}
+
+  # The process-wide config, built once on first use. The returned node is
+  # SHARED: treat it as read-only. Callers that need to mutate should use
+  # make_config, which always returns a fresh copy.
+  def shared_config do
+    cached = :persistent_term.get(@shared_key, nil)
+
+    if cached != nil and usable?(cached) do
+      cached
+    else
+      cfg = make_config()
+      :persistent_term.put(@shared_key, cfg)
+      cfg
+    end
+  end
+
+  defp usable?(cfg) do
+    Voxgig.Struct.getprop(cfg, "main")
+    true
+  rescue
+    ArgumentError -> false
+  end
 end
 `)
     })

package/project/.sdk/src/cmp/elixir/fragment/Main.fragment.ex

@@ -18,7 +18,9 @@ defmodule ProjectName do
     utility = Utility.new()
     S.setprop(client, "_utility", utility)
 
-    config = ProjectName.Config.make_config()
+    # The process-wide config (sdkgen rung L2): read-only on the request path,
+    # so every client shares one rather than rebuilding it.
+    config = ProjectName.Config.shared_config()
 
     rootctx =
       Context.new(

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

@@ -91,6 +91,12 @@ function elixirString(s: string): string {
   return '"' + String(s)
     .replace(/\\/g, '\\\\')
     .replace(/"/g, '\\"')
+    // `#` escaped because Elixir INTERPOLATES `\#{...}` inside a double-quoted
+    // string. Without this a model value containing `#{` is evaluated as code
+    // at compile time rather than emitted as text - which is both a wrong
+    // value and an arbitrary-expression hole. Escaping every `#` is simpler to
+    // reason about than escaping only `#{`, and `\#` is just `#` in Elixir.
+    .replace(/#/g, '\\#')
     .replace(/\n/g, '\\n')
     .replace(/\t/g, '\\t')
     + '"'

package/project/.sdk/src/cmp/haskell/Config_haskell.ts

@@ -2,22 +2,20 @@ import {
   Content,
   File,
   cmp,
-  each,
-  isAuthActive,
-  resolveAuthPrefix,
+  configDefinition,
+  configReprSetting,
+  isConfigData,
 } from '@voxgig/sdkgen'
 
 
 import {
-  KIT,
   Model,
-  getModelPath,
 } from '@voxgig/apidef'
 
 
 import {
-  clean,
   formatHsValue,
+  hsString,
 } from './utility_haskell'
 
 
@@ -38,50 +36,36 @@ const Config = cmp(async function Config(props: any) {
 
   const model: Model = ctx$.model
 
-  const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // The same config as an OBJECT, built by the shared helper so this target's
+  // literal and the data that replaces it above the threshold are the same
+  // config by construction. The JSON is what the threshold is measured on -
+  // emitted source size varies by language, the model does not.
+  const { def: configDef, json: configJson } = configDefinition(model)
+  const asData = isConfigData(configJson, configReprSetting(model))
+
+  // ABOVE THE THRESHOLD: emit the model as DATA.
+  //
+  // The literal representation is one enormous CV expression. GHC type-checks
+  // and desugars every constructor application in it, and buildCV then walks
+  // the whole tree allocating an IORef per node. A string constant is one
+  // token, and jsonRead builds the same Value from it directly.
+  //
+  // Both branches return a FRESH Value per call - buildCV allocates new
+  // IORefs, jsonRead re-parses - so a caller that mutates one config cannot
+  // reach another's, exactly as before.
+  const configBody = asData
+    ? `-- THE API MODEL, EMBEDDED AS DATA (sdkgen rung L1).
+--
+-- Emitted only above a size threshold, or when \`main.kit.config.repr\` pins
+-- it: for a small model the CV literal is smaller and far easier to read when
+-- debugging.
+configData :: String
+configData = ${hsString(configJson)}
 
-  const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
-
-  const authActive = isAuthActive(model)
-  const authPrefix = resolveAuthPrefix(model)
-
-  let baseUrl = ''
-  try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
-
-  const featureConfig: any = {}
-  each(feature, (f: any) => {
-    featureConfig[f.name] = f.config || {}
-  })
-
-  const entityOptions: any = {}
-  each(entity, (ent: any) => {
-    entityOptions[ent.name] = {}
-  })
-
-  const options: any = {
-    base: baseUrl,
-    headers,
-    entity: entityOptions,
-  }
-  if (authActive) {
-    options.auth = { prefix: authPrefix }
-  }
-
-  const entityConfig = Object.values(entity || {}).reduce((a: any, n: any) => (
-    a[n.name] = clean({
-      fields: n.fields,
-      name: n.name,
-      op: n.op,
-      relations: n.relations,
-    }, true), a), {})
-
-  const config = {
-    main: { name: model.const.Name },
-    feature: featureConfig,
-    options,
-    entity: entityConfig,
-  }
+makeConfig :: IO Value
+makeConfig = jsonRead configData`
+    : `makeConfig :: IO Value
+makeConfig = buildCV ${formatHsValue(configDef)}`
 
   File({ name: 'SdkConfig.' + target.ext }, () => {
 
@@ -90,12 +74,11 @@ const Config = cmp(async function Config(props: any) {
 module SdkConfig (makeConfig, makeFeature) where
 
 import VoxgigStruct (Value)
-import SdkHelpers (CV (..), buildCV)
+import ${asData ? 'SdkJson (jsonRead)' : 'SdkHelpers (CV (..), buildCV)'}
 import SdkTypes (Feature)
 import qualified SdkFeatures as F
 
-makeConfig :: IO Value
-makeConfig = buildCV ${formatHsValue(config)}
+${configBody}
 
 makeFeature :: String -> IO Feature
 makeFeature name = case name of

package/project/.sdk/src/cmp/haskell/Package_haskell.ts

@@ -39,6 +39,7 @@ library
     hs-source-dirs:   src
     exposed-modules:  VoxgigStruct
                       Vregex
+                      SdkJson
                       SdkTypes
                       SdkHelpers
                       SdkRuntime

package/project/.sdk/src/cmp/haskell/Test_haskell.ts

@@ -257,7 +257,7 @@ import qualified SdkFeatures as F
 import qualified SdkClient as C
 import qualified TReadmeExamples
 import Testutil
-import TestJson (jsonRead)
+import SdkJson (jsonRead)
 
 -- Load an entity fixture (../.sdk/test/entity/<name>/<Name>TestData.json).
 loadFixture :: String -> IO Value

package/project/.sdk/src/cmp/haskell/utility_haskell.ts

@@ -54,9 +54,20 @@ function hsString(s: string): string {
 
 
 // Render a JSON-shaped value as a Haskell `CV` literal (the generated
-// SdkConfig realises it with buildCV). Keys sorted for byte-stable output;
-// empty map/list render as (CVMap []) / (CVList []) — valid for 0, 1 or N
-// entries (N-feature-safe).
+// SdkConfig realises it with buildCV). Empty map/list render as
+// (CVMap []) / (CVList []) — valid for 0, 1 or N entries (N-feature-safe).
+//
+// KEY ORDER IS INSERTION ORDER, not sorted. struct's Haskell `Value` holds a
+// map as an ORDERED assoc list, so key order is observable — it survives into
+// keysof, iteration and stringify. This used to sort, which was fine while
+// this was the only representation, but above the size threshold the same
+// config arrives via jsonRead in the JSON text's order. Sorting here would
+// have made the two representations describe the same config in a different
+// order, which is exactly what rung L1 promises cannot happen.
+//
+// Insertion order is still byte-stable: every nested level of the config comes
+// from `each`, which iterates sorted, and the two levels built by hand
+// (the root, and `options`) have a fixed order every target's literal follows.
 function formatHsValue(val: any): string {
   if (val === null || val === undefined) {
     return 'CVNull'
@@ -75,8 +86,7 @@ function formatHsValue(val: any): string {
     return '(CVList [' + items + '])'
   }
   if (typeof val === 'object') {
-    const keys = Object.keys(val).sort()
-    const items = keys
+    const items = Object.keys(val)
       .map((k) => '(' + hsString(k) + ', ' + formatHsValue(val[k]) + ')')
       .join(', ')
     return '(CVMap [' + items + '])'

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

@@ -101,6 +101,27 @@ public final class Config {
     return (Map<String, Object>) Json.parse(configJson());
   }
 
+  // SHARED CONFIG (sdkgen rung L2).
+  //
+  // The SDK reads the config on every request and never writes to it, so one
+  // instance is shared by every client rather than rebuilt per client - the
+  // difference between parsing the embedded JSON once and once per client.
+  //
+  // Initialization-on-demand holder: the JLS guarantees the class initializer
+  // runs once, lazily, and safely under concurrency, with no locking on the
+  // read path.
+  private static final class SharedHolder {
+    static final Map<String, Object> VALUE = makeConfig();
+  }
+
+  // The process-wide config, built once on first use.
+  //
+  // The returned map is SHARED: treat it as read-only. Callers that need to
+  // mutate should use makeConfig, which always parses a fresh copy.
+  public static Map<String, Object> sharedConfig() {
+    return SharedHolder.VALUE;
+  }
+
   public static Feature makeFeature(String name) {
     switch (name) {
 `)

package/project/.sdk/src/cmp/kotlin/Config_kotlin.ts

@@ -93,6 +93,21 @@ object Config {
     return Json.parse(configJson()) as MutableMap<String, Any?>
   }
 
+  // SHARED CONFIG (sdkgen rung L2).
+  //
+  // The SDK reads the config on every request and never writes to it, so one
+  // instance is shared by every client rather than rebuilt per client - the
+  // difference between parsing the embedded JSON once and once per client.
+  //
+  // 'by lazy' defaults to LazyThreadSafetyMode.SYNCHRONIZED, so concurrent
+  // first calls build it exactly once.
+  //
+  // The returned map is SHARED: treat it as read-only. Callers that need to
+  // mutate should use makeConfig, which always parses a fresh copy.
+  private val sharedConfigVal: MutableMap<String, Any?> by lazy { makeConfig() }
+
+  fun sharedConfig(): MutableMap<String, Any?> = sharedConfigVal
+
   fun makeFeature(name: String): Feature {
     return when (name) {
 `)