@voxgig/sdkgen 4.33.0 → 4.34.1

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

@@ -1,5 +1,7 @@
 // ProjectName SDK utility: makePoint - endpoint resolution.
 
+using System.Text.RegularExpressions;
+
 using Voxgig.Struct;
 
 namespace ProjectNameSdk.Util;
@@ -27,6 +29,50 @@ public static partial class SdkUtility
         return parts[parts.Count - 1] is string last && last.StartsWith("{");
     }
 
+    private static readonly Regex PathParamRe = new Regex("^\\{([^{}/]+)\\}\\z");
+
+    private static Dictionary<string, object?>? OwnPoint(List<Dictionary<string, object?>> points)
+    {
+        var best = points[0];
+        foreach (var candidate in points)
+        {
+            var candTerm = TerminalParam(candidate);
+            var bestTerm = TerminalParam(best);
+            if (candTerm != bestTerm)
+            {
+                if (candTerm)
+                {
+                    best = candidate;
+                }
+            }
+            else if (PartsLen(candidate) < PartsLen(best))
+            {
+                best = candidate;
+            }
+        }
+        return best;
+    }
+
+    // The path parameters of a point that neither the call nor the entity
+    // gives a value for, looked up as ParamUtil looks them up.
+    private static List<string> UnfilledParams(Context ctx, Dictionary<string, object?>? point)
+    {
+        var missing = new List<string>();
+        if (StructUtils.GetProp(point, "parts") is not List<object?> parts)
+        {
+            return missing;
+        }
+        foreach (var part in parts)
+        {
+            var found = PathParamRe.Match(part as string ?? "");
+            if (found.Success && ParamValue(ctx, point, found.Groups[1].Value) == null)
+            {
+                missing.Add(found.Groups[1].Value);
+            }
+        }
+        return missing;
+    }
+
     internal static Dictionary<string, object?>? MakePointUtil(Context ctx)
     {
         if (ctx.Out.TryGetValue("point", out var outPoint) && outPoint != null)
@@ -48,8 +94,9 @@ public static partial class SdkUtility
         var op = ctx.Op!;
         var options = ctx.Options;
 
-        var allowOp = StructUtils.GetPath(options, StructUtils.Jt("allow", "op")) as string ?? "";
-        if (!allowOp.Contains(op.Name))
+        var allowOpVal = StructUtils.GetPath(options, StructUtils.Jt("allow", "op"));
+        var allowOp = allowOpVal as string ?? "";
+        if (!global::ProjectNameSdk.Helpers.Allowed(allowOpVal, op.Name))
         {
             throw ctx.MakeError("point_op_allow",
                 "Operation \"" + op.Name +
@@ -146,23 +193,27 @@ public static partial class SdkUtility
                         "\" is not valid.");
                 }
 
-                point = op.Points[0];
-                foreach (var candidate in op.Points)
+                // A call without an action falls back to a point without one,
+                // as generation does, and only to a route the call can fill.
+                var plain = op.Points.Where(candidate => StructUtils.GetProp(
+                    Helpers.ToMapAny(StructUtils.GetProp(candidate, "select")), "$action") == null).ToList();
+                if (plain.Count == 0)
                 {
-                    var candTerm = TerminalParam(candidate);
-                    var bestTerm = TerminalParam(point);
-                    if (candTerm != bestTerm)
-                    {
-                        if (candTerm)
-                        {
-                            point = candidate;
-                        }
-                    }
-                    else if (PartsLen(candidate) < PartsLen(point))
-                    {
-                        point = candidate;
-                    }
+                    throw ctx.MakeError("point_action_required",
+                        "Operation \"" + op.Name +
+                        "\" has only action endpoints; pass $action to choose one.");
+                }
+                var fillable = plain.Where(candidate => UnfilledParams(ctx, candidate).Count == 0).ToList();
+
+                if (fillable.Count == 0)
+                {
+                    throw ctx.MakeError("point_no_match",
+                        "Operation \"" + op.Name +
+                        "\" has no endpoint whose path parameters are all given (missing: " +
+                        string.Join(", ", UnfilledParams(ctx, OwnPoint(plain))) + ").");
                 }
+
+                point = OwnPoint(fillable);
             }
 
             if (reqselector != null)

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

@@ -9,10 +9,19 @@ public static partial class SdkUtility
 {
     internal static Spec MakeSpecUtil(Context ctx)
     {
-        if (ctx.Out.TryGetValue("spec", out var outSpec) && outSpec is Spec cached)
+        if (ctx.Out.TryGetValue("spec", out var outSpec))
         {
-            ctx.Spec = cached;
-            return cached;
+            // A PreSpec hook (validate) rejects the operation by placing its
+            // error here; the pipeline raises it, and ctx.Spec stays a spec.
+            if (outSpec is Exception rejected)
+            {
+                throw rejected;
+            }
+            if (outSpec is Spec cached)
+            {
+                ctx.Spec = cached;
+                return cached;
+            }
         }
 
         var point = ctx.Point;
@@ -36,11 +45,11 @@ public static partial class SdkUtility
 
         ctx.Spec.Method = utility.PrepareMethod(ctx);
 
-        var allowMethod = StructUtils.GetPath(options, StructUtils.Jt("allow", "method"))
-            as string ?? "";
+        var allowMethodVal = StructUtils.GetPath(options, StructUtils.Jt("allow", "method"));
+        var allowMethod = allowMethodVal as string ?? "";
         // null-safe: an op outside the convention resolves NO method (see
         // PrepareMethod), which the allow list can never contain.
-        if (ctx.Spec.Method == null || !allowMethod.Contains(ctx.Spec.Method))
+        if (!global::ProjectNameSdk.Helpers.Allowed(allowMethodVal, ctx.Spec.Method))
         {
             throw ctx.MakeError("spec_method_allow",
                 "Method \"" + ctx.Spec.Method +
@@ -77,8 +86,17 @@ public static partial class SdkUtility
             ctx.Ctrl.Explain["spec"] = ctx.Spec;
         }
 
+        // Whatever PrepareAuth sets in the query, under whichever name, is the
+        // credential; a key it leaves as it was is the caller's.
+        var query = new Dictionary<string, object?>(ctx.Spec.Query);
+
         var spec = utility.PrepareAuth(ctx);
 
+        spec.AuthQuery = spec.Query
+            .Where(e => !query.TryGetValue(e.Key, out var was) || !Equals(was, e.Value))
+            .Select(e => e.Key)
+            .ToList();
+
         ctx.Spec = spec;
         return spec;
     }

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

@@ -9,6 +9,8 @@ namespace ProjectNameSdk.Util;
 
 public static partial class SdkUtility
 {
+    private static readonly Regex PlaceholderRe = new Regex("\\{[^{}/]+\\}");
+
     internal static string MakeUrlUtil(Context ctx)
     {
         var spec = ctx.Spec ?? throw ctx.MakeError("url_no_spec",
@@ -20,6 +22,9 @@ public static partial class SdkUtility
             StructUtils.Jt(spec.Base, spec.Prefix, spec.Path, spec.Suffix), "/", true);
         var resmatch = new Dictionary<string, object?>();
 
+        // Sent with the request, never recorded as the entity's match.
+        var authquery = spec.AuthQuery;
+
         // A route the definition ends with a slash keeps it: a server such as
         // a Django REST one redirects or refuses the route without it.
         if (ctx.Point != null && StructUtils.GetProp(ctx.Point, "orig") is string orig &&
@@ -40,6 +45,18 @@ public static partial class SdkUtility
             }
         }
 
+        // A placeholder left in the route would send the request to the wrong
+        // route. The base's own placeholders are server variables, resolved
+        // with the options.
+        var baseUrl = (spec.Base ?? "").TrimEnd('/');
+        var route = url.StartsWith(baseUrl, System.StringComparison.Ordinal) ? url.Substring(baseUrl.Length) : url;
+        var unfilled = PlaceholderRe.Matches(route).Select(m => m.Value).ToList();
+        if (unfilled.Count > 0)
+        {
+            throw ctx.MakeError("url_param_missing",
+                "URL path has no value for " + string.Join(", ", unfilled) + ".");
+        }
+
         // Append query string from spec.Query.
         var qsep = "?";
         foreach (var item in StructUtils.Items(spec.Query))
@@ -51,7 +68,10 @@ public static partial class SdkUtility
                 url += qsep + StructUtils.EscUrl(key) + "=" +
                     StructUtils.EscUrl(StructUtils.Stringify(val));
                 qsep = "&";
-                resmatch[key] = val;
+                if (!authquery.Contains(key))
+                {
+                    resmatch[key] = val;
+                }
             }
         }
 

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

@@ -0,0 +1,124 @@
+// ProjectName SDK utility: media.
+
+using Voxgig.Struct;
+
+namespace ProjectNameSdk.Util;
+
+// The media types a point declares: `response` (the model's `rs`) for the
+// Accept header, and `body` (the model's `rb`) for the request body.
+public static partial class SdkUtility
+{
+    // The data key holding a raw request body. Like `$action`, it can never
+    // be a declared argument name.
+    internal const string RawBody = "$body";
+
+    internal static bool IsJsonMedia(object? media)
+    {
+        var m = (media as string ?? "").Split(';', 2)[0].Trim().ToLowerInvariant();
+        return m == "application/json" || m == "text/json" || m.EndsWith("+json");
+    }
+
+    // The declared JSON type alone, else every declared type in the model's
+    // order; null when no success response declares a body.
+    internal static string? AcceptOf(object? point)
+    {
+        var res = StructUtils.GetProp(point, "response");
+        if (StructUtils.GetProp(res, "media") is not string media || media == "")
+        {
+            return null;
+        }
+        if ("json".Equals(StructUtils.GetProp(res, "kind")))
+        {
+            return media;
+        }
+        var types = new List<string> { media };
+        if (StructUtils.GetProp(res, "alternatives") is List<object?> alts)
+        {
+            foreach (var alt in alts)
+            {
+                if (StructUtils.GetProp(alt, "media") is string m && m != "")
+                {
+                    types.Add(m);
+                }
+            }
+        }
+        return string.Join(", ", types);
+    }
+
+    internal static bool IsRawRequest(object? point)
+    {
+        return "raw".Equals(StructUtils.GetProp(StructUtils.GetProp(point, "body"), "kind"));
+    }
+
+    internal static bool IsJsonRequest(object? point)
+    {
+        return "json".Equals(StructUtils.GetProp(StructUtils.GetProp(point, "body"), "kind"));
+    }
+
+    // Bytes or a stream go as given. A map or a list is JSON, and so is a
+    // scalar on a point that declares a JSON body.
+    internal static object RequestBody(object? point, object body)
+    {
+        if (body is byte[] || body is Stream)
+        {
+            return body;
+        }
+        if (StructUtils.IsNode(body) || IsJsonRequest(point))
+        {
+            return StructUtils.Jsonify(body);
+        }
+        return body;
+    }
+
+    private static bool HasHeader(Dictionary<string, object?> headers, string name)
+    {
+        return headers.Keys.Any(k => k.ToLowerInvariant() == name);
+    }
+
+    // A caller's accept wins. A declared request type replaces each JSON
+    // content-type, the SDK default, and leaves any other the caller set.
+    internal static Dictionary<string, object?> MediaHeaders(object? point,
+        Dictionary<string, object?> headers)
+    {
+        var accept = AcceptOf(point);
+        if (accept != null && !HasHeader(headers, "accept"))
+        {
+            headers["accept"] = accept;
+        }
+
+        var body = StructUtils.GetProp(point, "body");
+        var kind = StructUtils.GetProp(body, "kind");
+        if (("raw".Equals(kind) || "json".Equals(kind)) &&
+            StructUtils.GetProp(body, "media") is string media && media != "")
+        {
+            foreach (var k in new List<string>(headers.Keys))
+            {
+                if (k.ToLowerInvariant() == "content-type" && IsJsonMedia(headers[k]))
+                {
+                    headers.Remove(k);
+                }
+            }
+            if (!HasHeader(headers, "content-type"))
+            {
+                headers["content-type"] = media;
+            }
+        }
+
+        return headers;
+    }
+
+    // Bytes, a Stream or a string, sent as they are. A Stream can be read
+    // once, so it is read here, before the first attempt, and a retry sends
+    // the same bytes again.
+    internal static object? RawBodyOf(Dictionary<string, object?>? reqdata)
+    {
+        var body = reqdata != null && reqdata.TryGetValue(RawBody, out var found) ? found : null;
+        if (body is Stream stream)
+        {
+            using var buffer = new MemoryStream();
+            stream.CopyTo(buffer);
+            return buffer.ToArray();
+        }
+        return body;
+    }
+}

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

@@ -10,13 +10,6 @@ public static partial class SdkUtility
 {
     internal static object? ParamUtil(Context ctx, object? paramdef)
     {
-        var point = ctx.Point;
-        var spec = ctx.Spec;
-        var match = ctx.Match;
-        var reqmatch = ctx.Reqmatch;
-        var data = ctx.Data;
-        var reqdata = ctx.Reqdata;
-
         var pt = StructUtils.Typify(paramdef);
 
         string key;
@@ -29,39 +22,83 @@ public static partial class SdkUtility
             key = StructUtils.GetProp(paramdef, "name") as string ?? "";
         }
 
-        var akey = "";
+        var akey = ParamAlias(ctx.Point, key);
+        if (ctx.Spec != null && akey != "" &&
+            StructUtils.GetProp(ctx.Reqmatch, key) == null && StructUtils.GetProp(ctx.Match, key) == null)
+        {
+            ctx.Spec.Alias[akey] = key;
+        }
+
+        return ParamValue(ctx, ctx.Point, key);
+    }
+
+    // The name a point gives a parameter in the call, if it renames it.
+    private static string ParamAlias(Dictionary<string, object?>? point, string key)
+    {
         if (point != null)
         {
             var alias = Helpers.ToMapAny(StructUtils.GetProp(point, "alias"));
             if (alias != null && StructUtils.GetProp(alias, key) is string ak)
             {
-                akey = ak;
+                return ak;
             }
         }
+        return "";
+    }
+
+    // The value the call or its entity gives a point's parameter, under its
+    // name or the point's alias for it.
+    internal static object? ParamValue(Context ctx, Dictionary<string, object?>? point, string key)
+    {
+        var akey = ParamAlias(point, key);
 
-        var val = StructUtils.GetProp(reqmatch, key);
+        var val = StructUtils.GetProp(ctx.Reqmatch, key);
 
-        val ??= StructUtils.GetProp(match, key);
+        val ??= StructUtils.GetProp(ctx.Match, key);
 
         if (val == null && akey != "")
         {
-            if (spec != null)
-            {
-                spec.Alias[akey] = key;
-            }
-            val = StructUtils.GetProp(reqmatch, akey);
+            val = StructUtils.GetProp(ctx.Reqmatch, akey);
         }
 
-        val ??= StructUtils.GetProp(reqdata, key);
+        val ??= StructUtils.GetProp(ctx.Reqdata, key);
 
-        val ??= StructUtils.GetProp(data, key);
+        val ??= StructUtils.GetProp(ctx.Data, key);
 
         if (val == null && akey != "")
         {
-            val = StructUtils.GetProp(reqdata, akey);
-            val ??= StructUtils.GetProp(data, akey);
+            val = StructUtils.GetProp(ctx.Reqdata, akey);
+            val ??= StructUtils.GetProp(ctx.Data, akey);
         }
 
         return val;
     }
+
+    // The arguments a point declares in one location, query or header, each
+    // with the name it travels under and the value this call passes in its
+    // match or else its data. Unlike a path parameter, the entity's stored
+    // match and data never supply one.
+    internal static List<(string Name, string Wire, object? Val)> CallArgs(Context ctx, string kind)
+    {
+        var args = new List<(string Name, string Wire, object? Val)>();
+        if (ctx.Point != null &&
+            StructUtils.GetPath(ctx.Point, StructUtils.Jt("args", kind)) is List<object?> defs)
+        {
+            foreach (var ad in defs)
+            {
+                if (StructUtils.GetProp(ad, "name") is not string name || name == "")
+                {
+                    continue;
+                }
+                var wire = StructUtils.GetProp(ad, "orig") is string orig && orig != "" ? orig : name;
+                var val = ctx.Reqmatch == null ? null : StructUtils.GetProp(ctx.Reqmatch, name);
+                if (val == null && ctx.Reqdata != null)
+                {
+                    val = StructUtils.GetProp(ctx.Reqdata, name);
+                }
+                args.Add((name, wire, val));
+            }
+        }
+        return args;
+    }
 }

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

@@ -10,6 +10,10 @@ public static partial class SdkUtility
 
         if (op.Input == "data")
         {
+            if (IsRawRequest(ctx.Point))
+            {
+                return RawBodyOf(ctx.Reqdata);
+            }
             var body = ctx.Utility!.TransformRequest(ctx);
             return body;
         }

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

@@ -1,5 +1,7 @@
 // ProjectName SDK utility: prepareHeaders.
 
+using System.Collections;
+
 using Voxgig.Struct;
 
 namespace ProjectNameSdk.Util;
@@ -11,42 +13,119 @@ public static partial class SdkUtility
         var options = ctx.Client!.OptionsMap();
 
         var headers = StructUtils.GetProp(options, "headers");
-        var result = (headers == null ? null : StructUtils.Clone(headers) as Dictionary<string, object?>)
-            ?? new Dictionary<string, object?>();
-
-        // A header parameter travels as a header, under the name the
-        // definition gives it, and only from this call's own arguments. It
-        // replaces a default of the same name, whatever its case.
-        if (ctx.Point != null &&
-            StructUtils.GetPath(ctx.Point, StructUtils.Jt("args", "header")) is List<object?> hl)
+        var result = MediaHeaders(ctx.Point,
+            (headers == null ? null : StructUtils.Clone(headers) as Dictionary<string, object?>)
+            ?? new Dictionary<string, object?>());
+
+        // A header argument replaces a default of the same name, whatever its
+        // case.
+        foreach (var arg in CallArgs(ctx, "header"))
+        {
+            if (arg.Val != null)
+            {
+                var key = arg.Wire.ToLowerInvariant();
+                foreach (var k in new List<string>(result.Keys))
+                {
+                    if (k.ToLowerInvariant() == key)
+                    {
+                        result.Remove(k);
+                    }
+                }
+                result[key] = StructUtils.Stringify(arg.Val);
+            }
+        }
+
+        // A cookie argument travels in the cookie header, form serialized and
+        // percent-encoded, replacing a cookie of the same name among those the
+        // caller's headers already send.
+        var sent = CallArgs(ctx, "cookie").Where(arg => arg.Val != null).ToList();
+        if (0 < sent.Count)
         {
-            foreach (var hd in hl)
+            var names = sent.SelectMany(arg => arg.Val is IDictionary map
+                ? CookieKeys(map).Select(key => StructUtils.EscUrl(key))
+                : new List<string> { arg.Wire }).ToList();
+            var kept = new List<string>();
+            foreach (var k in new List<string>(result.Keys))
             {
-                if (StructUtils.GetProp(hd, "name") is not string name || name == "")
+                if (k.ToLowerInvariant() != "cookie")
                 {
                     continue;
                 }
-                var wire = StructUtils.GetProp(hd, "orig") is string orig && orig != "" ? orig : name;
-                var val = ctx.Reqmatch == null ? null : StructUtils.GetProp(ctx.Reqmatch, name);
-                if (val == null && ctx.Reqdata != null)
+                if (result[k] is string given)
                 {
-                    val = StructUtils.GetProp(ctx.Reqdata, name);
+                    kept.AddRange(CookieKeep(given, names));
                 }
-                if (val != null)
+                result.Remove(k);
+            }
+            foreach (var arg in sent)
+            {
+                var pair = CookiePair(arg.Wire, arg.Val);
+                if ("" != pair)
                 {
-                    var key = wire.ToLowerInvariant();
-                    foreach (var k in new List<string>(result.Keys))
-                    {
-                        if (k.ToLowerInvariant() == key)
-                        {
-                            result.Remove(k);
-                        }
-                    }
-                    result[key] = StructUtils.Stringify(val);
+                    kept.Add(pair);
                 }
             }
+            if (0 < kept.Count)
+            {
+                result["cookie"] = string.Join("; ", kept);
+            }
         }
 
         return result;
     }
+
+    // The caller's cookie pieces with the named cookies removed: a cookie is
+    // one ;-delimited piece, whatever its value holds.
+    internal static List<string> CookieKeep(string header, List<string> names)
+    {
+        var kept = new List<string>();
+        foreach (var piece in header.Split(';'))
+        {
+            var cookie = piece.Trim();
+            if ("" != cookie && !names.Contains(cookie.Split('=', 2)[0].Trim()))
+            {
+                kept.Add(cookie);
+            }
+        }
+        return kept;
+    }
+
+    // The form style of a cookie parameter: a list repeats the name, a map
+    // sends its own keys, and every value is percent-encoded.
+    private static string CookiePair(string wire, object? val)
+    {
+        string Esc(object? v) => StructUtils.EscUrl(StructUtils.Stringify(v));
+        var pairs = new List<string>();
+        if (val is IList items)
+        {
+            foreach (var item in items)
+            {
+                pairs.Add(wire + "=" + Esc(item));
+            }
+        }
+        else if (val is IDictionary map)
+        {
+            foreach (var key in CookieKeys(map))
+            {
+                pairs.Add(StructUtils.EscUrl(key) + "=" + Esc(map[key]));
+            }
+        }
+        else
+        {
+            pairs.Add(wire + "=" + Esc(val));
+        }
+        return string.Join("; ", pairs);
+    }
+
+    // A map's keys as the struct port orders them, whatever the map's type.
+    private static List<string> CookieKeys(IDictionary map)
+    {
+        var keys = new List<string>();
+        foreach (var key in map.Keys)
+        {
+            keys.Add(Convert.ToString(key) ?? "");
+        }
+        keys.Sort(StringComparer.Ordinal);
+        return keys;
+    }
 }

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

@@ -31,19 +31,40 @@ public static partial class SdkUtility
             }
         }
 
-        // A header parameter travels in the headers, which PrepareHeaders
-        // fills.
+        // A header or cookie parameter travels in the headers, which
+        // PrepareHeaders fills, unless a query parameter shares its name: then
+        // both are sent.
+        var declared = new List<object?>();
+        if (point != null &&
+            StructUtils.GetPath(point, StructUtils.Jt("args", "query")) is List<object?> dql)
+        {
+            foreach (var qd in dql)
+            {
+                declared.Add(StructUtils.GetProp(qd, "name"));
+            }
+        }
         if (point != null &&
             StructUtils.GetPath(point, StructUtils.Jt("args", "header")) is List<object?> ahl)
         {
             foreach (var hd in ahl)
             {
-                if (StructUtils.GetProp(hd, "name") is string hname)
+                if (StructUtils.GetProp(hd, "name") is string hname && !declared.Contains(hname))
                 {
                     paramnames.Add(hname);
                 }
             }
         }
+        if (point != null &&
+            StructUtils.GetPath(point, StructUtils.Jt("args", "cookie")) is List<object?> acl)
+        {
+            foreach (var cd in acl)
+            {
+                if (StructUtils.GetProp(cd, "name") is string cname && !declared.Contains(cname))
+                {
+                    paramnames.Add(cname);
+                }
+            }
+        }
 
         // A query parameter travels under the name the definition gives it,
         // its orig, which the model may have renamed for the caller.
@@ -72,6 +93,15 @@ public static partial class SdkUtility
             }
         }
 
+        // A create or update passes its query arguments in its data.
+        foreach (var arg in CallArgs(ctx, "query"))
+        {
+            if (arg.Val != null && !ContainsStr(paramnames, arg.Name))
+            {
+                query[arg.Wire] = arg.Val;
+            }
+        }
+
         return query;
     }