@voxgig/sdkgen 1.3.8 → 1.3.9

package/project/.sdk/tm/csharp/core/Spec.cs

@@ -0,0 +1,81 @@
+// ProjectName SDK - HTTP request specification.
+
+namespace ProjectNameSdk;
+
+public class Spec
+{
+    public List<object?>? Parts;
+    public Dictionary<string, object?> Headers = new();
+    public Dictionary<string, object?> Alias = new();
+    public string Base = "";
+    public string Prefix = "";
+    public string Suffix = "";
+    public Dictionary<string, object?> Params = new();
+    public Dictionary<string, object?> Query = new();
+    public string Step = "";
+    public string Method = "GET";
+    public object? Body;
+    public string Url = "";
+    public string Path = "";
+
+    public Spec(Dictionary<string, object?>? specmap)
+    {
+        if (specmap == null)
+        {
+            return;
+        }
+
+        if (specmap.TryGetValue("parts", out var v) && v is List<object?> parts)
+        {
+            Parts = parts;
+        }
+        if (specmap.TryGetValue("headers", out v) && v is Dictionary<string, object?> h)
+        {
+            Headers = h;
+        }
+        if (specmap.TryGetValue("alias", out v) && v is Dictionary<string, object?> a)
+        {
+            Alias = a;
+        }
+        if (specmap.TryGetValue("base", out v) && v is string b)
+        {
+            Base = b;
+        }
+        if (specmap.TryGetValue("prefix", out v) && v is string p)
+        {
+            Prefix = p;
+        }
+        if (specmap.TryGetValue("suffix", out v) && v is string sf)
+        {
+            Suffix = sf;
+        }
+        if (specmap.TryGetValue("params", out v) && v is Dictionary<string, object?> pm)
+        {
+            Params = pm;
+        }
+        if (specmap.TryGetValue("query", out v) && v is Dictionary<string, object?> q)
+        {
+            Query = q;
+        }
+        if (specmap.TryGetValue("step", out v) && v is string st)
+        {
+            Step = st;
+        }
+        if (specmap.TryGetValue("method", out v) && v is string m)
+        {
+            Method = m;
+        }
+        if (specmap.TryGetValue("body", out v))
+        {
+            Body = v;
+        }
+        if (specmap.TryGetValue("url", out v) && v is string u)
+        {
+            Url = u;
+        }
+        if (specmap.TryGetValue("path", out v) && v is string pa)
+        {
+            Path = pa;
+        }
+    }
+}

package/project/.sdk/tm/csharp/core/Types.cs

@@ -0,0 +1,21 @@
+// ProjectName SDK - core contracts.
+
+namespace ProjectNameSdk;
+
+// The minimal entity contract the pipeline depends on (list-wrapping in
+// MakeResult, feature hooks). Concrete entity classes derive from
+// ProjectNameEntityBase which implements this.
+public interface IEntity
+{
+    string GetName();
+    IEntity Make();
+    object? Data(object? data = null);
+    object? Match(object? match = null);
+}
+
+// Transport function: performs the HTTP (or mock) request. Returns a
+// transport-shaped response map:
+//   { status, statusText, headers, json: Func<object?>, body }
+// Throws (typically ProjectNameError) on transport-level failure - the C#
+// twin of go's (any, error) return.
+public delegate object? FetcherFunc(Context ctx, string fullurl, Dictionary<string, object?> fetchdef);

package/project/.sdk/tm/csharp/core/Utility.cs

@@ -0,0 +1,88 @@
+// ProjectName SDK - utility object: the pluggable set of pipeline functions.
+// Every pipeline step is a delegate field so features (and custom utilities)
+// can wrap or replace behaviour per client instance.
+
+namespace ProjectNameSdk;
+
+public class Utility
+{
+    public Func<Context, object?, object?> Clean = null!;
+    public Func<Context, object?> Done = null!;
+    public Func<Context, Exception?, object?> MakeError = null!;
+    public Action<Context, Feature.BaseFeature> FeatureAdd = null!;
+    public Action<Context, string> FeatureHook = null!;
+    public Action<Context, Feature.BaseFeature> FeatureInit = null!;
+    public FetcherFunc Fetcher = null!;
+    public Func<Context, Dictionary<string, object?>> MakeFetchDef = null!;
+    public Func<Dictionary<string, object?>?, Context?, Context> MakeContext = null!;
+    public Func<Context, Dictionary<string, object?>> MakeOptions = null!;
+    public Func<Context, Response> MakeRequest = null!;
+    public Func<Context, Response> MakeResponse = null!;
+    public Func<Context, Result> MakeResult = null!;
+    public Func<Context, Dictionary<string, object?>?> MakePoint = null!;
+    public Func<Context, Spec> MakeSpec = null!;
+    public Func<Context, string> MakeUrl = null!;
+    public Func<Context, object?, object?> Param = null!;
+    public Func<Context, Spec> PrepareAuth = null!;
+    public Func<Context, object?> PrepareBody = null!;
+    public Func<Context, Dictionary<string, object?>> PrepareHeaders = null!;
+    public Func<Context, string> PrepareMethod = null!;
+    public Func<Context, Dictionary<string, object?>> PrepareParams = null!;
+    public Func<Context, string> PreparePath = null!;
+    public Func<Context, Dictionary<string, object?>> PrepareQuery = null!;
+    public Func<Context, Result> ResultBasic = null!;
+    public Func<Context, Result> ResultBody = null!;
+    public Func<Context, Result> ResultHeaders = null!;
+    public Func<Context, object?> TransformRequest = null!;
+    public Func<Context, object?> TransformResponse = null!;
+    public Dictionary<string, object?> Custom = new();
+
+    public Utility()
+    {
+        Util.SdkUtility.RegisterAll(this);
+    }
+
+    private Utility(bool _noregister)
+    {
+    }
+
+    // A shallow copy sharing the same delegates but with an independent
+    // Custom map, so per-entity utility views can diverge safely.
+    public static Utility Copy(Utility src)
+    {
+        var u = new Utility(true)
+        {
+            Clean = src.Clean,
+            Done = src.Done,
+            MakeError = src.MakeError,
+            FeatureAdd = src.FeatureAdd,
+            FeatureHook = src.FeatureHook,
+            FeatureInit = src.FeatureInit,
+            Fetcher = src.Fetcher,
+            MakeFetchDef = src.MakeFetchDef,
+            MakeContext = src.MakeContext,
+            MakeOptions = src.MakeOptions,
+            MakeRequest = src.MakeRequest,
+            MakeResponse = src.MakeResponse,
+            MakeResult = src.MakeResult,
+            MakePoint = src.MakePoint,
+            MakeSpec = src.MakeSpec,
+            MakeUrl = src.MakeUrl,
+            Param = src.Param,
+            PrepareAuth = src.PrepareAuth,
+            PrepareBody = src.PrepareBody,
+            PrepareHeaders = src.PrepareHeaders,
+            PrepareMethod = src.PrepareMethod,
+            PrepareParams = src.PrepareParams,
+            PreparePath = src.PreparePath,
+            PrepareQuery = src.PrepareQuery,
+            ResultBasic = src.ResultBasic,
+            ResultBody = src.ResultBody,
+            ResultHeaders = src.ResultHeaders,
+            TransformRequest = src.TransformRequest,
+            TransformResponse = src.TransformResponse,
+            Custom = new Dictionary<string, object?>(src.Custom),
+        };
+        return u;
+    }
+}

package/project/.sdk/tm/csharp/feature/AuditFeature.cs

@@ -0,0 +1,116 @@
+// Audit trail. Emits a structured record for every operation - who (actor),
+// what (entity + op), the outcome, and a correlation id - suitable for
+// compliance logging. Records accumulate on the feature (bounded by `max`,
+// default 1000) and, when a `sink` callback is supplied, are also pushed to
+// it (e.g. to forward to a SIEM). The actor is the per-call ctrl actor,
+// falling back to the options `actor`, then "anonymous". Each operation is
+// audited exactly once (the per-context marker in ctx.Out prevents a
+// PreDone + PreUnexpected double-log). Timestamps use the injectable `now`
+// clock so tests stay deterministic.
+
+using static ProjectNameSdk.Feature.FeatureOptions;
+
+namespace ProjectNameSdk.Feature;
+
+public class AuditFeature : BaseFeature
+{
+    private ProjectNameSDK? _client;
+    private Dictionary<string, object?>? _options;
+    private int _seq;
+
+    // Activity tracking (mirrors the ts client._audit record).
+    public List<Dictionary<string, object?>> Records = new();
+
+    private const string SeenKey = "audit_seen";
+
+    public AuditFeature()
+    {
+        Version = "0.0.1";
+        Name = "audit";
+        Active = true;
+    }
+
+    public override void Init(Context ctx, Dictionary<string, object?> options)
+    {
+        _client = ctx.Client;
+        _options = options;
+        Active = FoptBool(options, "active", false);
+        _seq = 0;
+    }
+
+    public override void PreDone(Context ctx)
+    {
+        // Outcome reflects the actual result; a non-2xx reaches PreDone
+        // before the pipeline errors.
+        var outcome = "error";
+        if (ctx.Result != null && ctx.Result.Ok && ctx.Result.Err == null)
+        {
+            outcome = "ok";
+        }
+        Emit(ctx, outcome);
+    }
+
+    public override void PreUnexpected(Context ctx)
+    {
+        Emit(ctx, "error");
+    }
+
+    private void Emit(Context ctx, string outcome)
+    {
+        if (!Active)
+        {
+            return;
+        }
+
+        // One record per operation (PreDone + a following PreUnexpected on a
+        // failure must not double-log).
+        if (ctx.Out.TryGetValue(SeenKey, out var seen) && Equals(seen, true))
+        {
+            return;
+        }
+        ctx.Out[SeenKey] = true;
+
+        _seq++;
+
+        var actor = "anonymous";
+        var optActor = FoptStr(_options, "actor", "");
+        if (optActor != "")
+        {
+            actor = optActor;
+        }
+        if (ctx.Ctrl != null && ctx.Ctrl.Actor != "")
+        {
+            actor = ctx.Ctrl.Actor;
+        }
+
+        var entity = ctx.Op?.Entity ?? "_";
+        var opname = ctx.Op?.Name ?? "_";
+
+        var record = new Dictionary<string, object?>
+        {
+            ["seq"] = _seq,
+            ["ts"] = FoptNow(_options)(),
+            ["actor"] = actor,
+            ["entity"] = entity,
+            ["op"] = opname,
+            ["outcome"] = outcome,
+            ["correlationId"] = ctx.Id,
+        };
+        if (ctx.Result != null)
+        {
+            record["status"] = ctx.Result.Status;
+        }
+
+        Records.Add(record);
+        var max = FoptInt(_options, "max", 1000);
+        while (Records.Count > max)
+        {
+            Records.RemoveAt(0);
+        }
+
+        if (Opt(_options, "sink") is Action<Dictionary<string, object?>> sink)
+        {
+            sink(record);
+        }
+    }
+}

package/project/.sdk/tm/csharp/feature/BaseFeature.cs

@@ -0,0 +1,39 @@
+// ProjectName SDK - feature base class. Features derive from this and
+// override the hooks they need; unimplemented hooks are no-ops.
+
+namespace ProjectNameSdk.Feature;
+
+public class BaseFeature
+{
+    public string Version = "0.0.1";
+    public string Name = "base";
+    public bool Active = true;
+
+    // AddOpts positions this feature when added via the client `extend`
+    // option: "__before__", "__after__" or "__replace__" name an
+    // already-added feature (mirrors the ts feature `_options`).
+    public Dictionary<string, object?>? AddOpts;
+
+    // AddOptions is read by the featureAdd utility to place this feature.
+    public virtual Dictionary<string, object?>? AddOptions() => AddOpts;
+
+    public virtual string GetVersion() => Version;
+    public virtual string GetName() => Name;
+    public virtual bool GetActive() => Active;
+
+    public virtual void Init(Context ctx, Dictionary<string, object?> options) { }
+
+    public virtual void PostConstruct(Context ctx) { }
+    public virtual void PostConstructEntity(Context ctx) { }
+    public virtual void SetData(Context ctx) { }
+    public virtual void GetData(Context ctx) { }
+    public virtual void GetMatch(Context ctx) { }
+    public virtual void SetMatch(Context ctx) { }
+    public virtual void PrePoint(Context ctx) { }
+    public virtual void PreSpec(Context ctx) { }
+    public virtual void PreRequest(Context ctx) { }
+    public virtual void PreResponse(Context ctx) { }
+    public virtual void PreResult(Context ctx) { }
+    public virtual void PreDone(Context ctx) { }
+    public virtual void PreUnexpected(Context ctx) { }
+}

package/project/.sdk/tm/csharp/feature/CacheFeature.cs

@@ -0,0 +1,186 @@
+// Response caching for safe (read) requests. Wraps the active transport and
+// serves a fresh cached snapshot instead of hitting the network when the
+// same method+URL was fetched within `ttl` ms (default: 5000). Only
+// successful (2xx) responses to cacheable methods (default: GET) are
+// stored, keyed by method+URL. The cache is bounded (`max` entries, default
+// 256, oldest evicted first) and every hit/miss/bypass is counted. Bodies
+// are snapshotted on capture so both the current caller and later hits can
+// re-read the JSON body repeatedly.
+
+using static ProjectNameSdk.Feature.FeatureOptions;
+
+namespace ProjectNameSdk.Feature;
+
+public class CacheFeature : BaseFeature
+{
+    private ProjectNameSDK? _client;
+    private Dictionary<string, object?>? _options;
+    private Dictionary<string, CacheEntry> _store = new();
+    private List<string> _order = new();
+
+    // Activity tracking (mirrors the ts client._cache record).
+    public int Hit;
+    public int Miss;
+    public int Bypass;
+
+    private class CacheEntry
+    {
+        public long Expiry;
+        public CacheSnapshot Snapshot = new();
+    }
+
+    private class CacheSnapshot
+    {
+        public int Status;
+        public string StatusText = "";
+        public object? Data;
+        public Dictionary<string, object?> Headers = new();
+    }
+
+    public CacheFeature()
+    {
+        Version = "0.0.1";
+        Name = "cache";
+        Active = true;
+    }
+
+    public override void Init(Context ctx, Dictionary<string, object?> options)
+    {
+        _client = ctx.Client;
+        _options = options;
+        Active = FoptBool(options, "active", false);
+
+        if (!Active)
+        {
+            return;
+        }
+
+        _store = new Dictionary<string, CacheEntry>();
+        _order = new List<string>();
+
+        var inner = ctx.Utility!.Fetcher;
+
+        ctx.Utility.Fetcher = (ctx2, url, fetchdef) => Through(ctx2, url, fetchdef, inner);
+    }
+
+    private object? Through(Context ctx, string url, Dictionary<string, object?> fetchdef,
+        FetcherFunc inner)
+    {
+        var method = "GET";
+        if (fetchdef.TryGetValue("method", out var mraw) && mraw is string m && m != "")
+        {
+            method = m.ToUpperInvariant();
+        }
+
+        var methods = FoptStrList(_options, "methods") ?? new List<string> { "GET" };
+        var cacheable = methods.Any(x => x.ToUpperInvariant() == method);
+        if (!cacheable)
+        {
+            return inner(ctx, url, fetchdef);
+        }
+
+        var key = method + " " + url;
+        var now = FoptNow(_options)();
+
+        if (_store.TryGetValue(key, out var hit) && hit.Expiry > now)
+        {
+            Hit++;
+            return Replay(hit.Snapshot);
+        }
+
+        object? res = null;
+        Exception? err = null;
+        try
+        {
+            res = inner(ctx, url, fetchdef);
+        }
+        catch (Exception ex)
+        {
+            err = ex;
+        }
+
+        if (err == null && Storable(res))
+        {
+            var snapshot = Snapshot(res);
+            var ttl = FoptInt(_options, "ttl", 5000);
+            Evict();
+            _store[key] = new CacheEntry { Expiry = now + ttl, Snapshot = snapshot };
+            _order.Add(key);
+            Miss++;
+            return Replay(snapshot);
+        }
+
+        Bypass++;
+        if (err != null)
+        {
+            throw err;
+        }
+        return res;
+    }
+
+    private static bool Storable(object? res)
+    {
+        var (status, has) = FresStatus(res);
+        return has && status >= 200 && status < 300;
+    }
+
+    private static CacheSnapshot Snapshot(object? res)
+    {
+        var rm = res as Dictionary<string, object?>;
+        var snap = new CacheSnapshot();
+
+        var (status, has) = FresStatus(res);
+        if (has)
+        {
+            snap.Status = status;
+        }
+        if (rm != null)
+        {
+            if (rm.TryGetValue("statusText", out var st) && st is string sts)
+            {
+                snap.StatusText = sts;
+            }
+            if (rm.TryGetValue("json", out var jf) && jf is Func<object?> f)
+            {
+                snap.Data = f();
+            }
+            if (rm.TryGetValue("headers", out var hraw) && hraw is Dictionary<string, object?> headers)
+            {
+                foreach (var kv in headers)
+                {
+                    snap.Headers[kv.Key.ToLowerInvariant()] = kv.Value;
+                }
+            }
+        }
+
+        return snap;
+    }
+
+    // Replay builds a fresh transport-shaped response so the body stays
+    // re-readable for every consumer.
+    private static Dictionary<string, object?> Replay(CacheSnapshot snap)
+    {
+        var data = snap.Data;
+        var headers = new Dictionary<string, object?>(snap.Headers);
+        return new Dictionary<string, object?>
+        {
+            ["status"] = snap.Status,
+            ["statusText"] = snap.StatusText,
+            ["body"] = "not-used",
+            ["json"] = (Func<object?>)(() => data),
+            ["headers"] = headers,
+        };
+    }
+
+    // Evict drops oldest entries (FIFO) until the store is under `max`.
+    private void Evict()
+    {
+        var max = FoptInt(_options, "max", 256);
+        while (_store.Count >= max && _order.Count > 0)
+        {
+            var oldest = _order[0];
+            _order.RemoveAt(0);
+            _store.Remove(oldest);
+        }
+    }
+}

package/project/.sdk/tm/csharp/feature/ClienttrackFeature.cs

@@ -0,0 +1,103 @@
+// Client tracking. Establishes a stable per-client session id at
+// construction and stamps identifying headers on every request: a
+// `User-Agent` (`<clientName>/<clientVersion>`), an `X-Client-Id` (session),
+// and a fresh per-request `X-Request-Id`. This lets a server correlate all
+// traffic from one SDK instance and each individual call. Header names,
+// client name/version and the id generator (`idgen`) are configurable;
+// caller-provided User-Agent / X-Client-Id values are never clobbered.
+
+using static ProjectNameSdk.Feature.FeatureOptions;
+
+namespace ProjectNameSdk.Feature;
+
+public class ClienttrackFeature : BaseFeature
+{
+    private ProjectNameSDK? _client;
+    private Dictionary<string, object?>? _options;
+
+    // Activity tracking (mirrors the ts client._clienttrack record).
+    public string Session = "";
+    public int Requests;
+    public string LastRequestID = "";
+    public string ClientName = "";
+
+    public ClienttrackFeature()
+    {
+        Version = "0.0.1";
+        Name = "clienttrack";
+        Active = true;
+    }
+
+    public override void Init(Context ctx, Dictionary<string, object?> options)
+    {
+        _client = ctx.Client;
+        _options = options;
+        Active = FoptBool(options, "active", false);
+        Requests = 0;
+    }
+
+    public override void PostConstruct(Context ctx)
+    {
+        if (!Active)
+        {
+            return;
+        }
+        Session = FoptStr(_options, "sessionId", Genid("session"));
+        ClientName = NameVersion();
+    }
+
+    public override void PreRequest(Context ctx)
+    {
+        if (!Active)
+        {
+            return;
+        }
+
+        var spec = ctx.Spec;
+        if (spec == null)
+        {
+            return;
+        }
+        spec.Headers ??= new Dictionary<string, object?>();
+
+        // Lazily establish the session when PostConstruct never fired.
+        if (Session == "")
+        {
+            Session = FoptStr(_options, "sessionId", Genid("session"));
+        }
+
+        var h = FoptMap(_options, "headers");
+        Requests++;
+        var requestId = Genid("request");
+
+        FheaderSetDefault(spec.Headers, FoptStr(h, "agent", "User-Agent"), NameVersion());
+        FheaderSetDefault(spec.Headers, FoptStr(h, "client", "X-Client-Id"), Session);
+        spec.Headers[FoptStr(h, "request", "X-Request-Id")] = requestId;
+
+        LastRequestID = requestId;
+        ClientName = NameVersion();
+    }
+
+    private string NameVersion()
+    {
+        var name = FoptStr(_options, "clientName", "ProjectName-SDK");
+        var version = FoptStr(_options, "clientVersion", "0.0.1");
+        return name + "/" + version;
+    }
+
+    private string Genid(string kind)
+    {
+        if (Opt(_options, "idgen") is Func<string, string> idgen)
+        {
+            return idgen(kind);
+        }
+        var id = string.Format("{0}-{1:x6}{2:x6}{3:x6}", kind[..1],
+            Random.Shared.Next(0x1000000), Random.Shared.Next(0x1000000),
+            Random.Shared.Next(0x1000000));
+        if (id.Length > 20)
+        {
+            id = id[..20];
+        }
+        return id;
+    }
+}