@voxgig/sdkgen 3.4.6 → 3.5.0

package/project/.sdk/tm/csharp/utility/MakeOptions.cs

@@ -1,12 +1,20 @@
 // ProjectName SDK utility: makeOptions - merge, validate and derive the
 // client options.
 
+using System.Text.RegularExpressions;
+
 using Voxgig.Struct;
 
 namespace ProjectNameSdk.Util;
 
 public static partial class SdkUtility
 {
+    // {name} placeholders in a templated server URL (OpenAPI server
+    // variables). Compiled once: MakeOptions runs per client construction.
+    private static readonly Regex ServerVarRe =
+        new(@"\{([A-Za-z0-9_]+)\}", RegexOptions.Compiled);
+
+
     internal static Dictionary<string, object?> MakeOptionsUtil(Context ctx)
     {
         var options = ctx.Options ?? new Dictionary<string, object?>();
@@ -73,6 +81,14 @@ public static partial class SdkUtility
             {
                 ["`$CHILD`"] = "`$STRING`",
             },
+            // OpenAPI server-variable defaults, carried by the generated
+            // config whenever the spec's server URL is templated. Accepted
+            // here so validation does not reject the SDK's own config; the
+            // {name} substitution into base is a separate concern.
+            ["server"] = new Dictionary<string, object?>
+            {
+                ["`$CHILD`"] = "",
+            },
             ["allow"] = new Dictionary<string, object?>
             {
                 ["method"] = "GET,PUT,POST,PATCH,DELETE,OPTIONS",
@@ -118,12 +134,62 @@ public static partial class SdkUtility
         var merged = StructUtils.Merge(new List<object?>
         {
             new Dictionary<string, object?>(),
-            cfgopts,
+            // CLONE the config side. `config` is a process-wide singleton
+            // (SdkConfig.SharedConfig), and Merge uses its nested maps as
+            // merge TARGETS - without this, one client's options (headers,
+            // server, ...) are written into the shared config and inherited by
+            // every client constructed afterwards.
+            StructUtils.Clone(cfgopts),
             opts,
         });
         var validated = StructUtils.Validate(merged, optspec);
         opts = validated as Dictionary<string, object?> ?? new Dictionary<string, object?>();
 
+        // Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
+        // Every placeholder must resolve to a non-empty value: from
+        // options.server (user), else the Config default. A placeholder that
+        // resolves to "" is a construction ERROR in live mode - the URL cannot
+        // work - but in test mode substitutes the deterministic value
+        // "test-<name>" so offline tests need no configuration. The SDK
+        // constructor has no error return, so a missing required variable
+        // THROWS: this is construction-time misconfiguration.
+        if (opts.TryGetValue("base", out var baseRaw) && baseRaw is string baseUrl &&
+            baseUrl.Contains('{'))
+        {
+            var testmode =
+                StructUtils.GetPath(opts, StructUtils.Jt("test", "active")) is bool ta && ta ||
+                StructUtils.GetPath(opts, StructUtils.Jt("feature", "test", "active"))
+                    is bool fa && fa;
+
+            var server = opts.TryGetValue("server", out var sv) &&
+                sv is Dictionary<string, object?> svm
+                ? svm : new Dictionary<string, object?>();
+
+            var sdkname = StructUtils.GetPath(config, StructUtils.Jt("main", "name"))
+                is string mn && mn != "" ? mn : "SDK";
+
+            opts["base"] = ServerVarRe.Replace(baseUrl, m =>
+            {
+                var name = m.Groups[1].Value;
+                var val = server.TryGetValue(name, out var v) && v is string s ? s : "";
+                if (val == "")
+                {
+                    if (testmode)
+                    {
+                        return "test-" + name;
+                    }
+                    throw new ProjectNameError("server_var_required",
+                        sdkname + ": the server variable '" + name + "' is required: " +
+                        "the API base URL is '" + baseUrl + "' - pass " +
+                        "new Dictionary<string, object?> { [\"server\"] = new " +
+                        "Dictionary<string, object?> { [\"" + name + "\"] = \"...\" } } " +
+                        "in the SDK options",
+                        ctx);
+                }
+                return val;
+            });
+        }
+
         // Restore system.fetch.
         if (sysFetch != null)
         {

package/project/.sdk/tm/dart/lib/utility/MakeOptionsUtility.dart

@@ -1,3 +1,5 @@
+import '../ProjectNameError.dart';
+
 import 'voxgig_struct.dart' as vs;
 
 import 'FetcherUtility.dart';
@@ -55,6 +57,11 @@ dynamic makeOptions(dynamic ctx) {
     'clean': {
       'keys': 'key,token,id',
     },
+    // Server-variable values for a templated base URL (OpenAPI server
+    // variables): {name} placeholders in "base" are substituted from this
+    // map at construction. Spec defaults arrive via the generated config;
+    // user values override them. Mirrors go's make_options optspec.
+    'server': {'`\$CHILD`': ''},
   };
 
   // Dart specific: preserve the (function-valued) system.fetch across
@@ -95,6 +102,42 @@ dynamic makeOptions(dynamic ctx) {
 
   opts = vs.validate(opts, optspec);
 
+  // Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
+  // Every placeholder must resolve to a non-empty value: from options.server
+  // (user), else the Config default. A placeholder that resolves to '' is a
+  // construction ERROR in live mode — the URL cannot work — but in test mode
+  // substitutes the deterministic value `test-<name>` so offline tests need no
+  // configuration. The SDK constructor has no error return, so a missing
+  // required variable THROWS: construction-time misconfiguration.
+  final baseVal = vs.getprop(opts, 'base');
+  if (baseVal is String && baseVal.contains('{')) {
+    final testmode = true == vs.getpath(opts, 'test.active') ||
+        true == vs.getpath(opts, 'feature.test.active');
+    final server = vs.getprop(opts, 'server') ?? {};
+    final sdkname = (vs.getpath(config, 'main.name') ?? 'SDK').toString();
+
+    opts['base'] = baseVal.replaceAllMapped(
+      RegExp(r'\{([A-Za-z0-9_]+)\}'),
+      (m) {
+        final name = m.group(1) as String;
+        final raw = vs.getprop(server, name);
+        final val = raw is String ? raw : '';
+        if ('' == val) {
+          if (testmode) {
+            return 'test-' + name;
+          }
+          throw ProjectNameError(
+            'server_var_required',
+            "$sdkname: the server variable '$name' is required: the API base "
+            "URL is '$baseVal' — pass { 'server': { '$name': '...' } } in the "
+            'SDK options',
+          );
+        }
+        return val;
+      },
+    );
+  }
+
   final sys = vs.getprop(opts, 'system');
   if (sys is Map) {
     sys['fetch'] = sysFetch;

package/project/.sdk/tm/elixir/lib/projectname/utility.ex

@@ -263,15 +263,71 @@ defmodule ProjectName.Utility do
         "utility" => %{},
         "system" => %{},
         "test" => %{"active" => false, "entity" => %{"`$OPEN`" => true}},
-        "clean" => %{"keys" => "key,token,id"}
+        "clean" => %{"keys" => "key,token,id"},
+        # Server-variable values for a templated base URL (OpenAPI server
+        # variables): {name} placeholders in "base" are substituted from this
+        # map at construction. Spec defaults arrive via the generated config;
+        # user values override them. Mirrors go's make_options optspec - elixir
+        # was the only target validating options that did not accept it, so a
+        # spec with a templated server URL failed validation outright.
+        "server" => %{"`$CHILD`" => ""}
       })
 
     sys_fetch = S.getpath(opts0, "system.fetch")
 
-    merged = S.merge(S.jt([S.jm([]), cfgopts, opts0]))
+    # CLONE the config side: `config` is a process-wide singleton
+    # (ProjectName.Config.shared_config) and merge uses its nested nodes as
+    # merge TARGETS, so without this one client's options (headers, server,
+    # ...) are written into the shared config and inherited by every client
+    # constructed afterwards.
+    merged = S.merge(S.jt([S.jm([]), S.clone(cfgopts), opts0]))
     validated = S.validate(merged, optspec)
     opts = if S.ismap(validated), do: validated, else: S.jm([])
 
+    # Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
+    # Every placeholder must resolve to a non-empty value: from options.server
+    # (user), else the Config default. A placeholder that resolves to "" is a
+    # construction ERROR in live mode - the URL cannot work - but in test mode
+    # substitutes the deterministic value "test-<name>" so offline tests need
+    # no configuration. The SDK constructor has no error return, so a missing
+    # required variable RAISES: construction-time misconfiguration.
+    base = S.getprop(opts, "base")
+
+    if is_binary(base) and String.contains?(base, "{") do
+      testmode =
+        true == S.getpath(opts, "test.active") or
+          true == S.getpath(opts, "feature.test.active")
+
+      server = H.or_(S.getprop(opts, "server"), S.jm([]))
+      mn = S.getpath(config, "main.name")
+      sdkname = if is_binary(mn) and mn != "", do: mn, else: "SDK"
+
+      resolved =
+        Regex.replace(~r/\{([A-Za-z0-9_]+)\}/, base, fn _match, name ->
+          val = S.getprop(server, name)
+          val = if is_binary(val), do: val, else: ""
+
+          cond do
+            val != "" ->
+              val
+
+            testmode ->
+              "test-" <> name
+
+            true ->
+              raise ProjectName.Error,
+                code: "server_var_required",
+                sdk: "ProjectName",
+                msg:
+                  "#{sdkname}: the server variable '#{name}' is required: the API " <>
+                    "base URL is '#{base}' - pass %{\"server\" => %{\"#{name}\" => " <>
+                    "\"...\"}} in the SDK options"
+          end
+        end)
+
+      S.setprop(opts, "base", resolved)
+    end
+
     if sys_fetch != nil do
       sysnode = S.getprop(opts, "system")
 

package/project/.sdk/tm/haskell/{test/TestJson.hs → src/SdkJson.hs}

@@ -1,11 +1,15 @@
 -- Self-contained JSON reader building struct `Value` nodes directly (no
--- third-party dependency beyond the `array` boot library). Shared by the
--- struct corpus runner and the entity-fixture tests. Uses O(1) array indexing
--- so large corpora parse in linear time.
+-- third-party dependency beyond the `array` boot library). Uses O(1) array
+-- indexing so large corpora parse in linear time.
+--
+-- Lives in src/ rather than test/ because SdkConfig needs it: above a size
+-- threshold the API model is embedded as a JSON string constant and parsed
+-- once at load (sdkgen rung L1) instead of being built as a CV literal. It is
+-- still what the struct corpus runner and the entity-fixture tests use.
 
 {-# LANGUAGE LambdaCase #-}
 
-module TestJson (jsonRead) where
+module SdkJson (jsonRead) where
 
 import Data.Array (Array, listArray, (!))
 import Data.Char (chr)

package/project/.sdk/tm/haskell/src/SdkRuntime.hs

@@ -13,7 +13,7 @@ module SdkRuntime where
 import Control.Exception (throwIO)
 import Control.Monad (forM_, when)
 import Data.Bits ((.&.))
-import Data.Char (toUpper)
+import Data.Char (isAlphaNum, toUpper)
 import Data.IORef
 import qualified Data.Map.Strict as Map
 import System.IO.Unsafe (unsafePerformIO)
@@ -1016,6 +1016,11 @@ optSpecValue :: IO Value
 optSpecValue = do
   auth <- jo [("prefix", VStr "")]
   hdrs <- jo [("`$CHILD`", VStr "`$STRING`")]
+  -- OpenAPI server-variable defaults, carried by the generated config whenever
+  -- the spec's server URL is templated. Accepted here so validation does not
+  -- reject the SDK's own config; the {name} substitution into base is a
+  -- separate concern.
+  srv <- jo [("`$CHILD`", VStr "")]
   allow <- jo [("method", VStr "GET,PUT,POST,PATCH,DELETE,OPTIONS"), ("op", VStr "create,update,load,list,remove,command,direct,graphql")]
   entChild <- do a <- emptyMap; jo [("`$OPEN`", VBool True), ("active", VBool False), ("alias", a)]
   ent <- jo [("`$CHILD`", entChild)]
@@ -1027,7 +1032,7 @@ optSpecValue = do
   test <- jo [("active", VBool False), ("entity", testEnt)]
   clean <- jo [("keys", VStr "key,token,id")]
   jo [ ("apikey", VStr ""), ("base", VStr "http://localhost:8000"), ("prefix", VStr ""), ("suffix", VStr "")
-     , ("auth", auth), ("headers", hdrs), ("allow", allow), ("entity", ent), ("feature", feat)
+     , ("auth", auth), ("headers", hdrs), ("server", srv), ("allow", allow), ("entity", ent), ("feature", feat)
      , ("utility", utilm), ("system", sysm), ("test", test), ("clean", clean) ]
 
 makeOptionsUtil :: Context -> IO Value
@@ -1079,6 +1084,54 @@ makeOptionsUtil ctx = do
   merged <- merge mlist
   validated <- validate INone merged optspec
   opts <- case validated of VMap _ -> pure validated; _ -> emptyMap
+  -- Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
+  -- Every placeholder must resolve to a non-empty value: from options.server
+  -- (user), else the Config default. A placeholder that resolves to "" is a
+  -- construction ERROR in live mode - the URL cannot work - but in test mode
+  -- substitutes the deterministic value "test-<name>" so offline tests need no
+  -- configuration. The SDK constructor has no error return, so a missing
+  -- required variable THROWS: construction-time misconfiguration.
+  baseV <- getp opts "base"
+  case baseV of
+    VStr base | '{' `elem` base -> do
+      taV <- getpathS opts "test.active"
+      faV <- getpathS opts "feature.test.active"
+      -- Value has no Eq instance: match the constructor.
+      let isTrue v = case v of VBool b -> b; _ -> False
+          testmode = isTrue taV || isTrue faV
+      server <- getp opts "server"
+      mnV <- getpathS config "main.name"
+      let sdkname = case mnV of VStr s | not (null s) -> s; _ -> "SDK"
+
+      -- Scanned by hand: a placeholder is `{` followed by [A-Za-z0-9_]+ and
+      -- `}`; anything else is literal text, so a stray brace is left alone.
+      let resolve [] = pure []
+          resolve ('{' : rest) =
+            let (name, tail') = span (\c -> isAlphaNum c || '_' == c) rest
+            in case tail' of
+                 ('}' : more) | not (null name) -> do
+                   valV <- case server of VMap _ -> getp server name; _ -> pure VNoval
+                   let val = case valV of VStr s -> s; _ -> ""
+                   sub <- if not (null val)
+                     then pure val
+                     else if testmode
+                       then pure ("test-" ++ name)
+                       else do
+                         e <- jo [ ("code", VStr "server_var_required")
+                                 , ("msg", VStr (sdkname ++ ": the server variable '" ++
+                                     name ++ "' is required: the API base URL is '" ++
+                                     base ++ "' - pass server = { \"" ++ name ++
+                                     "\": \"...\" } in the SDK options"))
+                                 , ("sdk", VStr "ProjectName") ]
+                         throwIO (SdkException e)
+                   more' <- resolve more
+                   pure (sub ++ more')
+                 _ -> do r <- resolve rest; pure ('{' : r)
+          resolve (c : rest) = do r <- resolve rest; pure (c : r)
+      resolved <- resolve base
+      setp opts "base" (VStr resolved)
+    _ -> pure ()
+
   when (not (isNoval sysFetch)) $ do
     sys <- getp opts "system"
     case sys of

package/project/.sdk/tm/haskell/test/Runner.hs

@@ -10,7 +10,7 @@ import Data.IORef
 import System.Exit (exitFailure)
 
 import Testutil
-import TestJson (jsonRead)
+import SdkJson (jsonRead)
 import StructCorpus (runStructCorpus)
 import qualified TPipeline
 import qualified TFeature

package/project/.sdk/tm/haskell/test/StructCorpus.hs

@@ -14,7 +14,7 @@ import Data.List (intercalate, isPrefixOf)
 
 import VoxgigStruct
 import qualified Vregex
-import TestJson (jsonRead)
+import SdkJson (jsonRead)
 
 nullmark, undefmark, existsmark :: String
 nullmark = "__NULL__"

package/project/.sdk/tm/java/core/SdkClient.java

@@ -27,7 +27,9 @@ public abstract class SdkClient {
   protected SdkClient(Map<String, Object> options) {
     this.utility = new Utility();
 
-    Map<String, Object> config = Config.makeConfig();
+    // The process-wide config (sdkgen rung L2): read-only on the request path,
+    // so every client shares one rather than rebuilding it.
+    Map<String, Object> config = Config.sharedConfig();
 
     Map<String, Object> ctxmap = new LinkedHashMap<>();
     ctxmap.put("client", this);

package/project/.sdk/tm/java/utility/MakeOptions.java

@@ -93,7 +93,11 @@ final class MakeOptions {
 
     List<Object> mergeList = new ArrayList<>();
     mergeList.add(new LinkedHashMap<String, Object>());
-    mergeList.add(cfgopts);
+    // CLONE the config side: `config` is a process-wide singleton
+    // (Config.sharedConfig) and merge uses its nested maps as merge TARGETS, so
+    // without this one client's options (headers, server, ...) are written into
+    // the shared config and inherited by every client constructed afterwards.
+    mergeList.add(Struct.clone(cfgopts));
     mergeList.add(opts);
     Object merged = Struct.merge(mergeList);
 

package/project/.sdk/tm/kotlin/core/SdkClient.kt

@@ -21,7 +21,9 @@ abstract class SdkClient(sdkopts: MutableMap<String, Any?>?) {
   protected val rootctx: Context
 
   init {
-    val config = Config.makeConfig()
+    // The process-wide config (sdkgen rung L2): read-only on the request path,
+    // so every client shares one rather than rebuilding it.
+    val config = Config.sharedConfig()
 
     val ctxmap = linkedMapOf<String, Any?>()
     ctxmap["client"] = this

package/project/.sdk/tm/kotlin/utility/MakeOptions.kt

@@ -84,7 +84,11 @@ fun makeOptions(ctx: Context): MutableMap<String, Any?> {
 
   val mergeList = mutableListOf<Any?>()
   mergeList.add(linkedMapOf<String, Any?>())
-  mergeList.add(cfgopts)
+  // CLONE the config side: `config` is a process-wide singleton
+  // (Config.sharedConfig) and merge uses its nested maps as merge TARGETS, so
+  // without this one client's options (headers, server, ...) are written into
+  // the shared config and inherited by every client constructed afterwards.
+  mergeList.add(Struct.clone(cfgopts))
   mergeList.add(opts)
   val merged = Struct.merge(mergeList)
 

package/project/.sdk/tm/ocaml/Makefile

@@ -14,7 +14,7 @@ INC = -I utility -I . -I test
 # The shared JSON corpus lives in the sibling .sdk workspace.
 CORPUS = ../.sdk/test/test.json
 
-RUNTIME = utility/vregex.ml utility/voxgig_struct.ml \
+RUNTIME = utility/vregex.ml utility/voxgig_struct.ml sdk_json.ml \
   sdk_types.ml sdk_helpers.ml sdk_runtime.ml sdk_features.ml
 
 ENTITIES = $(sort $(wildcard sdk_entity_*.ml))
@@ -33,7 +33,8 @@ SDK_TEST = $(RUNTIME) sdk_config.ml $(ENTITIES) sdk_client.ml sdk_error.ml \
   test/t_pipeline.ml test/t_feature.ml test/custom_utility.ml \
   $(ENTITY_TESTS) $(DOC_TESTS) test/t_main.ml
 
-CORPUS_SRC = utility/vregex.ml utility/voxgig_struct.ml test/struct_corpus.ml
+CORPUS_SRC = utility/vregex.ml utility/voxgig_struct.ml sdk_json.ml \
+  test/struct_corpus.ml
 
 .PHONY: test test-sdk test-corpus build lint clean
 

package/project/.sdk/tm/ocaml/sdk_json.ml

@@ -0,0 +1,106 @@
+(* JSON text -> voxgig struct value.
+ *
+ * A dependency-free reader, so the SDK can parse JSON with no opam packages -
+ * the same position every other target is in (elixir's ProjectName.Json,
+ * clojure's sdk.core/json-parse, the json_parse in c/rust/zig).
+ *
+ * It lives in the RUNTIME rather than the test tree because the generated
+ * config uses it: above a size threshold the API model is emitted as a JSON
+ * string constant and parsed here (sdkgen rung L1) instead of as a literal the
+ * compiler has to walk. `test/struct_corpus.ml` uses this same function rather
+ * than its own copy, so the corpus and the SDK cannot disagree about what a
+ * given JSON text means.
+ *
+ * Numbers are read as Num (float), which is exactly what formatOcamlValue
+ * emits for the literal form - so the two representations cannot disagree
+ * about the type of a whole number.
+ *)
+
+open Voxgig_struct
+
+(* ---------------- JSON reader -> value ---------------- *)
+
+let json_read (s : string) : value =
+  let n = String.length s in
+  let pos = ref 0 in
+  let peek () = if !pos < n then Some s.[!pos] else None in
+  let adv () = incr pos in
+  let skip_ws () =
+    while !pos < n && (match s.[!pos] with ' ' | '\t' | '\n' | '\r' -> true | _ -> false) do incr pos done
+  in
+  let rec pval () =
+    skip_ws ();
+    match peek () with
+    | Some '{' -> pobj ()
+    | Some '[' -> parr ()
+    | Some '"' -> Str (pstr ())
+    | Some 't' -> pos := !pos + 4; Bool true
+    | Some 'f' -> pos := !pos + 5; Bool false
+    | Some 'n' -> pos := !pos + 4; Null
+    | _ -> pnum ()
+  and pobj () =
+    adv (); skip_ws ();
+    if peek () = Some '}' then (adv (); empty_map ())
+    else begin
+      let m = empty_map () in
+      let rec loop () =
+        skip_ws ();
+        let k = pstr () in
+        skip_ws (); adv (); (* : *)
+        let v = pval () in
+        ignore (setprop m (Str k) v);
+        skip_ws ();
+        let c = (match peek () with Some c -> adv (); c | None -> '}') in
+        if c = ',' then loop () else m
+      in loop ()
+    end
+  and parr () =
+    adv (); skip_ws ();
+    if peek () = Some ']' then (adv (); empty_list ())
+    else begin
+      let acc = ref [] in
+      let rec loop () =
+        let v = pval () in
+        acc := v :: !acc;
+        skip_ws ();
+        let c = (match peek () with Some c -> adv (); c | None -> ']') in
+        if c = ',' then loop () else lst (List.rev !acc)
+      in loop ()
+    end
+  and pstr () =
+    adv ();
+    let b = Buffer.create 16 in
+    let rec loop () =
+      let c = s.[!pos] in adv ();
+      if c = '"' then Buffer.contents b
+      else if c = '\\' then begin
+        let e = s.[!pos] in adv ();
+        (match e with
+         | '"' -> Buffer.add_char b '"' | '\\' -> Buffer.add_char b '\\'
+         | '/' -> Buffer.add_char b '/' | 'n' -> Buffer.add_char b '\n'
+         | 't' -> Buffer.add_char b '\t' | 'r' -> Buffer.add_char b '\r'
+         | 'b' -> Buffer.add_char b '\b' | 'f' -> Buffer.add_char b '\012'
+         | 'u' ->
+           let hex = String.sub s !pos 4 in pos := !pos + 4;
+           let code = int_of_string ("0x" ^ hex) in
+           if code < 128 then Buffer.add_char b (Char.chr code)
+           else if code < 2048 then begin
+             Buffer.add_char b (Char.chr (0xC0 lor (code lsr 6)));
+             Buffer.add_char b (Char.chr (0x80 lor (code land 0x3F)))
+           end else begin
+             Buffer.add_char b (Char.chr (0xE0 lor (code lsr 12)));
+             Buffer.add_char b (Char.chr (0x80 lor ((code lsr 6) land 0x3F)));
+             Buffer.add_char b (Char.chr (0x80 lor (code land 0x3F)))
+           end
+         | c -> Buffer.add_char b c);
+        loop ()
+      end else (Buffer.add_char b c; loop ())
+    in loop ()
+  and pnum () =
+    let start = !pos in
+    while !pos < n && (match s.[!pos] with
+        | '0'..'9' | '-' | '+' | '.' | 'e' | 'E' -> true | _ -> false) do incr pos done;
+    let tok = String.sub s start (!pos - start) in
+    Num (float_of_string tok)
+  in
+  pval ()

package/project/.sdk/tm/ocaml/sdk_runtime.ml

@@ -905,6 +905,11 @@ let opt_spec_value () : value =
     ("system", empty_map ());
     ("test", jo [("active", Bool false); ("entity", jo [("`$OPEN`", Bool true)])]);
     ("clean", jo [("keys", Str "key,token,id")]);
+      (* Server-variable values for a templated base URL (OpenAPI server
+       * variables): {name} placeholders in "base" are substituted from this
+       * map at construction. Spec defaults arrive via the generated config;
+       * user values override them. Mirrors go's make_options optspec. *)
+      ("server", jo [("`$CHILD`", Str "")]);
   ]
 
 let make_options_util (ctx : ctx) : value =
@@ -946,6 +951,57 @@ let make_options_util (ctx : ctx) : value =
   let merged = merge (ja [empty_map (); cfgopts; opts]) in
   let validated = validate merged optspec in
   let opts = match validated with Map _ as m -> m | _ -> empty_map () in
+  (* Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
+     Every placeholder must resolve to a non-empty value: from options.server
+     (user), else the Config default. A placeholder that resolves to "" is a
+     construction ERROR in live mode - the URL cannot work - but in test mode
+     substitutes the deterministic value "test-<name>" so offline tests need no
+     configuration. The SDK constructor has no error return, so a missing
+     required variable RAISES: construction-time misconfiguration.
+
+     Scanned by hand: a placeholder is `{` followed by [A-Za-z0-9_]+ and `}`;
+     anything else is literal text, so a stray brace is left alone. *)
+  (match getp opts "base" with
+   | Str base when String.contains base '{' ->
+     let is_true v = match v with Bool b -> b | _ -> false in
+     let testmode =
+       is_true (getpath_s opts "test.active")
+       || is_true (getpath_s opts "feature.test.active") in
+     let server = match getp opts "server" with Map _ as m -> m | _ -> empty_map () in
+     let sdkname =
+       match getpath_s config "main.name" with Str s when s <> "" -> s | _ -> "SDK" in
+     let namechar c =
+       (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z')
+       || (c >= '0' && c <= '9') || c = '_' in
+     let buf = Buffer.create (String.length base) in
+     let n = String.length base in
+     let i = ref 0 in
+     while !i < n do
+       if base.[!i] <> '{' then begin
+         Buffer.add_char buf base.[!i];
+         incr i
+       end else begin
+         let j = ref (!i + 1) in
+         while !j < n && namechar base.[!j] do incr j done;
+         if !j >= n || base.[!j] <> '}' || !j = !i + 1 then begin
+           Buffer.add_char buf base.[!i];
+           incr i
+         end else begin
+           let name = String.sub base (!i + 1) (!j - !i - 1) in
+           let value = match getp server name with Str s -> s | _ -> "" in
+           if value <> "" then Buffer.add_string buf value
+           else if testmode then Buffer.add_string buf ("test-" ^ name)
+           else
+             raise (Sdk_error_exc (ctx_make_error ctx "server_var_required"
+               (sdkname ^ ": the server variable '" ^ name ^ "' is required: the API "
+                ^ "base URL is '" ^ base ^ "' - pass ~server:[(\"" ^ name
+                ^ "\", \"...\")] in the SDK options")));
+           i := !j + 1
+         end
+       end
+     done;
+     setp opts "base" (Str (Buffer.contents buf))
+   | _ -> ());
   (if not (is_noval sys_fetch) then
      match getp opts "system" with
      | Map _ as sys -> setp sys "fetch" sys_fetch