@voxgig/sdkgen 1.3.8 → 1.3.9

package/project/.sdk/tm/py/feature/idempotency_feature.py

@@ -0,0 +1,89 @@
+# ProjectName SDK idempotency feature
+
+from __future__ import annotations
+import random
+
+from feature.base_feature import ProjectNameBaseFeature
+
+
+# Idempotency keys for mutating operations. Adds an `Idempotency-Key`
+# header (name configurable via `header`) to unsafe requests so a server
+# can de-duplicate retried writes. The key is set once, at PreRequest,
+# before the request is built — so it is stable across transport-level
+# retries of the same call. A caller-supplied header is never overwritten
+# (case-insensitive). The key generator (`keygen`) is injectable for
+# deterministic tests.
+class ProjectNameIdempotencyFeature(ProjectNameBaseFeature):
+    def __init__(self):
+        super().__init__()
+        self.version = "0.0.1"
+        self.name = "idempotency"
+        self.active = True
+        self.client = None
+        self.options = {}
+
+    def init(self, ctx, options):
+        self.client = ctx.client
+        self.options = options if isinstance(options, dict) else {}
+
+        if self.options.get("active") is True:
+            self.active = True
+        else:
+            self.active = False
+
+    def PreRequest(self, ctx):
+        if not self.active:
+            return
+
+        spec = ctx.spec
+        if spec is None:
+            return
+
+        if not self._mutating(ctx):
+            return
+
+        header = self.options.get("header") or "Idempotency-Key"
+        if spec.headers is None:
+            spec.headers = {}
+
+        # Respect a key the caller already provided.
+        if self._existing(spec.headers, header) is not None:
+            return
+
+        key = self._genkey()
+        spec.headers[header] = key
+
+        client = self.client
+        track = getattr(client, "_idempotency", None)
+        if track is None:
+            track = {"issued": 0, "last": None}
+            client._idempotency = track
+        track["issued"] += 1
+        track["last"] = key
+
+    def _mutating(self, ctx):
+        methods = self.options.get("methods") or ["POST", "PUT", "PATCH", "DELETE"]
+        method = ""
+        if ctx.spec is not None and ctx.spec.method is not None:
+            method = str(ctx.spec.method).upper()
+        if method != "" and method in methods:
+            return True
+        opname = ctx.op.name if ctx.op is not None else None
+        ops = self.options.get("ops") or ["create", "update", "remove"]
+        return opname in ops
+
+    def _existing(self, headers, header):
+        lower = header.lower()
+        for key in headers:
+            if str(key).lower() == lower:
+                return headers[key]
+        return None
+
+    def _genkey(self):
+        keygen = self.options.get("keygen")
+        if callable(keygen):
+            return keygen()
+        return "%04x%04x%04x%04x%04x%04x" % (
+            random.randint(0, 0xFFFF), random.randint(0, 0xFFFF),
+            random.randint(0, 0xFFFF), random.randint(0, 0xFFFF),
+            random.randint(0, 0xFFFF), random.randint(0, 0xFFFF))

package/project/.sdk/tm/py/feature/metrics_feature.py

@@ -0,0 +1,93 @@
+# ProjectName SDK metrics feature
+
+from __future__ import annotations
+import time
+
+from feature.base_feature import ProjectNameBaseFeature
+
+
+# Statistics capture. Records per-operation counters and latency for every
+# call: totals plus a breakdown keyed by `<entity>.<op>`. Timing starts at
+# endpoint resolution (PrePoint) and stops when the call returns (PreDone)
+# or fails (PreUnexpected). Aggregates live on `client._metrics`. The clock
+# is injectable (`now`) for deterministic tests.
+class ProjectNameMetricsFeature(ProjectNameBaseFeature):
+    def __init__(self):
+        super().__init__()
+        self.version = "0.0.1"
+        self.name = "metrics"
+        self.active = True
+        self.client = None
+        self.options = {}
+
+    def init(self, ctx, options):
+        self.client = ctx.client
+        self.options = options if isinstance(options, dict) else {}
+
+        if self.options.get("active") is True:
+            self.active = True
+        else:
+            self.active = False
+
+        client = self.client
+        if getattr(client, "_metrics", None) is None:
+            client._metrics = {
+                "total": {"count": 0, "ok": 0, "err": 0, "totalMs": 0, "maxMs": 0},
+                "ops": {},
+            }
+
+    def PrePoint(self, ctx):
+        if not self.active:
+            return
+        ctx._metrics_start = self._now()
+
+    def PreDone(self, ctx):
+        if not self.active:
+            return
+        # Classify by the actual result: a 4xx/5xx that flows through still
+        # reaches PreDone before the pipeline raises.
+        result = ctx.result
+        ok = result is not None and result.ok is not False and result.err is None
+        self._record(ctx, ok)
+
+    def PreUnexpected(self, ctx):
+        if not self.active:
+            return
+        self._record(ctx, False)
+
+    def _record(self, ctx, ok):
+        # Record once per operation. When a non-2xx result reaches PreDone
+        # the pipeline then raises, firing PreUnexpected too; the missing
+        # start marker makes the second call a no-op.
+        start = getattr(ctx, "_metrics_start", None)
+        if start is None:
+            return
+        del ctx._metrics_start
+
+        dur = max(0, self._now() - start)
+
+        metrics = self.client._metrics
+        key = "_"
+        if ctx.op is not None:
+            key = (ctx.op.entity or "_") + "." + (ctx.op.name or "_")
+
+        op_bucket = metrics["ops"].get(key)
+        if op_bucket is None:
+            op_bucket = {"count": 0, "ok": 0, "err": 0, "totalMs": 0, "maxMs": 0}
+            metrics["ops"][key] = op_bucket
+
+        self._bump(metrics["total"], ok, dur)
+        self._bump(op_bucket, ok, dur)
+
+    def _bump(self, bucket, ok, dur):
+        bucket["count"] += 1
+        bucket["ok" if ok else "err"] += 1
+        bucket["totalMs"] += dur
+        if dur > bucket["maxMs"]:
+            bucket["maxMs"] = dur
+
+    def _now(self):
+        now = self.options.get("now")
+        if callable(now):
+            return now()
+        return time.time() * 1000

package/project/.sdk/tm/py/feature/netsim_feature.py

@@ -0,0 +1,170 @@
+# ProjectName SDK netsim feature
+
+from __future__ import annotations
+import time
+
+from feature.base_feature import ProjectNameBaseFeature
+
+
+# Network behaviour simulation. Wraps the active transport (the live
+# fetch or the `test` feature's in-memory mock) and injects realistic
+# network conditions so offline unit tests can exercise slowness,
+# transient failures, rate limiting and outages deterministically.
+#
+# Every injection mode is counter-driven (per client instance) so tests
+# are reproducible without mocking timers. `failRate` adds optional
+# pseudo-random failures via a seeded LCG for coverage-style testing.
+class ProjectNameNetsimFeature(ProjectNameBaseFeature):
+    def __init__(self):
+        super().__init__()
+        self.version = "0.0.1"
+        self.name = "netsim"
+        self.active = True
+        self.client = None
+        self.options = {}
+        self.calls = 0
+        self.seed = 1
+
+    def init(self, ctx, options):
+        self.client = ctx.client
+        self.options = options if isinstance(options, dict) else {}
+
+        if self.options.get("active") is True:
+            self.active = True
+        else:
+            self.active = False
+
+        seed = self.options.get("seed")
+        self.seed = int(seed) if isinstance(seed, (int, float)) and int(seed) != 0 else 1
+
+        if not self.active:
+            return
+
+        utility = ctx.utility
+        inner = utility.fetcher
+
+        def netsim_fetcher(fctx, fullurl, fetchdef):
+            return self._simulate(fctx, fullurl, fetchdef, inner)
+
+        utility.fetcher = netsim_fetcher
+
+    def _simulate(self, ctx, url, fetchdef, inner):
+        opts = self.options
+        self.calls += 1
+        call = self.calls
+
+        # Record the simulated conditions for test/debug inspection.
+        applied = {}
+
+        # Total outage: every call fails at the transport level.
+        if opts.get("offline") is True:
+            self._sleep(self._pick_latency())
+            applied["offline"] = True
+            self._track(ctx, applied)
+            return None, ctx.make_error("netsim_offline",
+                'Simulated network offline (URL was: "' + url + '")')
+
+        # Connection-level errors for the first N calls (e.g. ECONNRESET).
+        if call <= int(opts.get("errorTimes") or 0):
+            self._sleep(self._pick_latency())
+            applied["error"] = True
+            self._track(ctx, applied)
+            return None, ctx.make_error("netsim_conn",
+                "Simulated connection error (call " + str(call) + ")")
+
+        # Rate-limit responses (HTTP 429 + Retry-After) for the first N calls.
+        if call <= int(opts.get("rateLimitTimes") or 0):
+            self._sleep(self._pick_latency())
+            applied["rateLimited"] = True
+            self._track(ctx, applied)
+            retry_after = opts.get("retryAfter")
+            retry_after = 0 if retry_after is None else retry_after
+            return self._respond(ctx, 429, None, {
+                "statusText": "Too Many Requests",
+                "headers": {"retry-after": str(retry_after)},
+            })
+
+        # Retryable failure status for the first N calls, or every Nth call.
+        fail_status = 503 if opts.get("failStatus") is None else opts.get("failStatus")
+        fail_every = int(opts.get("failEvery") or 0)
+        fail_rate = opts.get("failRate") or 0
+        fail_by_count = call <= int(opts.get("failTimes") or 0)
+        fail_by_every = fail_every > 0 and call % fail_every == 0
+        fail_by_rate = fail_rate > 0 and self._rand() < fail_rate
+        if fail_by_count or fail_by_every or fail_by_rate:
+            self._sleep(self._pick_latency())
+            applied["failStatus"] = fail_status
+            self._track(ctx, applied)
+            return self._respond(ctx, fail_status, None,
+                {"statusText": "Simulated Failure"})
+
+        # Otherwise: apply latency then delegate to the real transport.
+        latency = self._pick_latency()
+        applied["latency"] = latency
+        self._track(ctx, applied)
+        self._sleep(latency)
+        return inner(ctx, url, fetchdef)
+
+    # Latency in ms: a fixed number, or a uniform sample from {min,max}.
+    def _pick_latency(self):
+        latency = self.options.get("latency")
+        if latency is None:
+            return 0
+        if isinstance(latency, (int, float)) and not isinstance(latency, bool):
+            return 0 if latency < 0 else latency
+        if not isinstance(latency, dict):
+            return 0
+        mn = int(latency.get("min") or 0)
+        mx = mn if latency.get("max") is None else int(latency.get("max"))
+        if mx <= mn:
+            return mn
+        return mn + int(self._rand() * (mx - mn))
+
+    def _sleep(self, ms):
+        if ms is None or ms <= 0:
+            return
+        sleep = self.options.get("sleep")
+        if callable(sleep):
+            sleep(ms)
+            return
+        time.sleep(ms / 1000.0)
+
+    # Deterministic 0..1 pseudo-random via a linear congruential generator.
+    def _rand(self):
+        self.seed = (self.seed * 1103515245 + 12345) & 0x7FFFFFFF
+        return self.seed / 0x7FFFFFFF
+
+    def _track(self, ctx, applied):
+        client = self.client
+        track = getattr(client, "_netsim", None)
+        if track is None:
+            track = {"calls": 0, "applied": []}
+            client._netsim = track
+        track["calls"] += 1
+        track["applied"].append(applied)
+        explain = getattr(ctx.ctrl, "explain", None) if ctx.ctrl is not None else None
+        if isinstance(explain, dict):
+            explain["netsim"] = track
+
+    # Build a transport-shaped response (matching the test feature's mock)
+    # with a lower-cased header map the result pipeline understands.
+    def _respond(self, ctx, status, data=None, extra=None):
+        out = {
+            "status": status,
+            "statusText": "OK",
+            "json": lambda: data,
+            "body": "not-used",
+        }
+        if isinstance(extra, dict):
+            for key, val in extra.items():
+                out[key] = val
+
+        headers = out.get("headers")
+        if not isinstance(headers, dict):
+            headers = {}
+        lower = {}
+        for key, val in headers.items():
+            lower[str(key).lower()] = val
+        out["headers"] = lower
+
+        return out, None

package/project/.sdk/tm/py/feature/paging_feature.py

@@ -0,0 +1,134 @@
+# ProjectName SDK paging feature
+
+from __future__ import annotations
+import re
+
+from feature.base_feature import ProjectNameBaseFeature
+
+
+# Pagination support for list operations. On the way out (PreRequest) it
+# stamps page/limit (or a cursor) into the request query; on the way back
+# (PreResult) it reads the server's pagination signals — a `Link:
+# rel="next"` header, `X-Page`/`X-Next-Page`/`X-Total-Count` headers, or
+# `next`/`cursor`/`nextCursor`/`hasMore` fields in the body — and records
+# them on `ctx.result.paging`. A per-call cursor/page supplied via ctrl
+# paging takes priority (used by auto-iteration). Parameter names
+# (`pageParam`/`limitParam`/`cursorParam`), `startPage` and page size
+# (`limit`) are configurable.
+class ProjectNamePagingFeature(ProjectNameBaseFeature):
+    def __init__(self):
+        super().__init__()
+        self.version = "0.0.1"
+        self.name = "paging"
+        self.active = True
+        self.client = None
+        self.options = {}
+
+    def init(self, ctx, options):
+        self.client = ctx.client
+        self.options = options if isinstance(options, dict) else {}
+
+        if self.options.get("active") is True:
+            self.active = True
+        else:
+            self.active = False
+
+    def PreRequest(self, ctx):
+        if not self.active:
+            return
+        if not self._is_list(ctx):
+            return
+        spec = ctx.spec
+        if spec is None:
+            return
+        if spec.query is None:
+            spec.query = {}
+
+        page_param = self.options.get("pageParam") or "page"
+        limit_param = self.options.get("limitParam") or "limit"
+        cursor_param = self.options.get("cursorParam") or "cursor"
+
+        # A per-call cursor/page from ctrl takes priority (auto-iteration).
+        paging = getattr(ctx.ctrl, "paging", None) if ctx.ctrl is not None else None
+        if not isinstance(paging, dict):
+            paging = {}
+
+        if paging.get("cursor") is not None:
+            spec.query[cursor_param] = paging["cursor"]
+        elif spec.query.get(page_param) is None:
+            page = paging.get("page")
+            if page is None:
+                page = self.options.get("startPage") or 1
+            spec.query[page_param] = page
+
+        if self.options.get("limit") is not None and spec.query.get(limit_param) is None:
+            spec.query[limit_param] = self.options.get("limit")
+
+    def PreResult(self, ctx):
+        if not self.active:
+            return
+        if not self._is_list(ctx):
+            return
+        result = ctx.result
+        if result is None:
+            return
+
+        headers = result.headers or {}
+        body = result.body
+
+        paging = {
+            "page": self._num(self._header(headers, "x-page")),
+            "totalCount": self._num(self._header(headers, "x-total-count")),
+            "nextPage": self._num(self._header(headers, "x-next-page")),
+            "next": None,
+            "cursor": None,
+            "hasMore": False,
+        }
+
+        # Link: <...>; rel="next"
+        link = self._header(headers, "link")
+        if link is not None:
+            m = re.search(r'<([^>]+)>\s*;\s*rel="?next"?', str(link), re.IGNORECASE)
+            if m:
+                paging["next"] = m.group(1)
+
+        # Body-level cursors.
+        if isinstance(body, dict):
+            if body.get("next") is not None:
+                paging["next"] = paging["next"] or body["next"]
+            if body.get("cursor") is not None:
+                paging["cursor"] = body["cursor"]
+            if body.get("nextCursor") is not None:
+                paging["cursor"] = body["nextCursor"]
+            if isinstance(body.get("hasMore"), bool):
+                paging["hasMore"] = body["hasMore"]
+
+        paging["hasMore"] = (paging["hasMore"]
+                             or paging["next"] is not None
+                             or paging["cursor"] is not None
+                             or paging["nextPage"] is not None)
+
+        result.paging = paging
+
+        self.client._paging = {"last": paging}
+
+    def _is_list(self, ctx):
+        ops = self.options.get("ops") or ["list"]
+        opname = ctx.op.name if ctx.op is not None else None
+        return opname in ops
+
+    def _header(self, headers, name):
+        lower = name.lower()
+        for key in headers:
+            if str(key).lower() == lower:
+                return headers[key]
+        return None
+
+    def _num(self, val):
+        if val is None:
+            return None
+        try:
+            n = float(val)
+        except (TypeError, ValueError):
+            return None
+        return int(n) if n.is_integer() else n

package/project/.sdk/tm/py/feature/proxy_feature.py

@@ -0,0 +1,104 @@
+# ProjectName SDK proxy feature
+
+from __future__ import annotations
+import os
+import re
+
+from feature.base_feature import ProjectNameBaseFeature
+
+
+# Outbound HTTP(S) proxy support. Wraps the active transport and attaches
+# proxy routing to each request's fetch definition. The proxy target comes
+# from options (`url`) or, when `fromEnv` is set, the standard
+# HTTPS_PROXY / HTTP_PROXY / NO_PROXY environment variables. The request is
+# annotated Python-idiomatically: `fetchdef["proxy"]` carries the proxy URL
+# and `fetchdef["proxies"]` carries a requests-style scheme map, for a
+# custom `system.fetch` transport to honour. An `agent` factory may also be
+# supplied (mirroring the ts target); its product is attached as
+# `fetchdef["agent"]` / `fetchdef["dispatcher"]`. Hosts matching `noProxy`
+# bypass the proxy.
+class ProjectNameProxyFeature(ProjectNameBaseFeature):
+    def __init__(self):
+        super().__init__()
+        self.version = "0.0.1"
+        self.name = "proxy"
+        self.active = True
+        self.client = None
+        self.options = {}
+        self.url = None
+        self.no_proxy = []
+
+    def init(self, ctx, options):
+        self.client = ctx.client
+        self.options = options if isinstance(options, dict) else {}
+
+        if self.options.get("active") is True:
+            self.active = True
+        else:
+            self.active = False
+
+        if not self.active:
+            return
+
+        self.url = self.options.get("url")
+        no_proxy = self.options.get("noProxy")
+
+        if self.options.get("fromEnv") is True:
+            self.url = (self.url
+                        or os.environ.get("HTTPS_PROXY") or os.environ.get("https_proxy")
+                        or os.environ.get("HTTP_PROXY") or os.environ.get("http_proxy"))
+            no_proxy = (no_proxy
+                        or os.environ.get("NO_PROXY") or os.environ.get("no_proxy"))
+
+        if isinstance(no_proxy, str):
+            no_proxy = re.split(r"\s*,\s*", no_proxy)
+        self.no_proxy = [s for s in (no_proxy or []) if s is not None and s != ""]
+
+        utility = ctx.utility
+        inner = utility.fetcher
+
+        def proxy_fetcher(fctx, fullurl, fetchdef):
+            fetchdef = self._route(fullurl, fetchdef)
+            return inner(fctx, fullurl, fetchdef)
+
+        utility.fetcher = proxy_fetcher
+
+    def _route(self, url, fetchdef):
+        if self.url is None or self._bypass(url):
+            return fetchdef
+
+        out = dict(fetchdef) if isinstance(fetchdef, dict) else {}
+        out["proxy"] = self.url
+        out["proxies"] = {"http": self.url, "https": self.url}
+
+        agent = self.options.get("agent")
+        if callable(agent):
+            # Factory returns a transport-specific agent/dispatcher.
+            made = agent(self.url, url)
+            out["dispatcher"] = made
+            out["agent"] = made
+
+        self._track(url)
+        return out
+
+    def _bypass(self, url):
+        if len(self.no_proxy) == 0:
+            return False
+        host = url
+        m = re.match(r"^[a-z]+://([^/:]+)", url, re.IGNORECASE)
+        if m:
+            host = m.group(1)
+        for np in self.no_proxy:
+            if np == "*":
+                return True
+            if host == np or host.endswith("." + re.sub(r"^\.", "", np)):
+                return True
+        return False
+
+    def _track(self, url):
+        client = self.client
+        track = getattr(client, "_proxy", None)
+        if track is None:
+            track = {"routed": 0, "url": self.url}
+            client._proxy = track
+        track["routed"] += 1

package/project/.sdk/tm/py/feature/ratelimit_feature.py

@@ -0,0 +1,98 @@
+# ProjectName SDK ratelimit feature
+
+from __future__ import annotations
+import math
+import time
+
+from feature.base_feature import ProjectNameBaseFeature
+
+
+# Client-side rate limiting via a token bucket. Each request consumes a
+# token; when the bucket is empty the request waits until the bucket
+# refills at `rate` tokens per second (with capacity `burst`, default:
+# `rate`). This keeps the client under a server's published quota rather
+# than discovering it via 429s. The clock (`now`) and the wait (`sleep`)
+# are injectable so the accounting can be tested deterministically without
+# wall-clock timing.
+class ProjectNameRatelimitFeature(ProjectNameBaseFeature):
+    def __init__(self):
+        super().__init__()
+        self.version = "0.0.1"
+        self.name = "ratelimit"
+        self.active = True
+        self.client = None
+        self.options = {}
+        self.tokens = 0
+        self.last = 0
+
+    def init(self, ctx, options):
+        self.client = ctx.client
+        self.options = options if isinstance(options, dict) else {}
+
+        if self.options.get("active") is True:
+            self.active = True
+        else:
+            self.active = False
+
+        if not self.active:
+            return
+
+        rate = self.options.get("rate") or 5
+        burst = rate if self.options.get("burst") is None else self.options.get("burst")
+        self.tokens = burst
+        self.last = self._now()
+
+        utility = ctx.utility
+        inner = utility.fetcher
+
+        def ratelimit_fetcher(fctx, fullurl, fetchdef):
+            self._acquire(fctx)
+            return inner(fctx, fullurl, fetchdef)
+
+        utility.fetcher = ratelimit_fetcher
+
+    def _acquire(self, ctx):
+        rate = self.options.get("rate") or 5
+        burst = rate if self.options.get("burst") is None else self.options.get("burst")
+
+        # Refill according to elapsed time.
+        now = self._now()
+        elapsed = now - self.last
+        self.last = now
+        self.tokens = min(burst, self.tokens + (elapsed / 1000.0) * rate)
+
+        if self.tokens >= 1:
+            self.tokens -= 1
+            return
+
+        # Not enough tokens: wait for one to accrue, then consume it.
+        needed = 1 - self.tokens
+        wait_ms = int(math.ceil((needed / rate) * 1000))
+        self._track(ctx, wait_ms)
+        self._sleep(wait_ms)
+        self.last = self._now()
+        self.tokens = 0
+
+    def _now(self):
+        now = self.options.get("now")
+        if callable(now):
+            return now()
+        return time.time() * 1000
+
+    def _sleep(self, ms):
+        if ms is None or ms <= 0:
+            return
+        sleep = self.options.get("sleep")
+        if callable(sleep):
+            sleep(ms)
+            return
+        time.sleep(ms / 1000.0)
+
+    def _track(self, ctx, wait_ms):
+        client = self.client
+        track = getattr(client, "_ratelimit", None)
+        if track is None:
+            track = {"throttled": 0, "waitMs": 0}
+            client._ratelimit = track
+        track["throttled"] += 1
+        track["waitMs"] += wait_ms