@voxgig/sdkgen 1.3.7 → 1.3.9

package/project/.sdk/tm/elixir/lib/projectname/feature/idempotency.ex

@@ -0,0 +1,107 @@
+# ProjectName SDK idempotency feature
+#
+# 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.
+
+defmodule ProjectName.Feature.Idempotency do
+  alias Voxgig.Struct, as: S
+  alias ProjectName.Feature, as: F
+
+  def new do
+    f = F.base("idempotency")
+    F.install(f, "init", fn ctx, opts -> init(f, ctx, opts) end)
+    F.install(f, "PreRequest", fn ctx -> pre_request(f, ctx) end)
+    f
+  end
+
+  def init(f, ctx, options) do
+    F.init_common(f, ctx, options)
+    nil
+  end
+
+  defp pre_request(f, ctx) do
+    if F.active?(f) do
+      spec = S.getprop(ctx, "spec")
+
+      if spec != nil and mutating(f, ctx) do
+        header = por(S.getprop(F.opts(f), "header"), "Idempotency-Key")
+
+        headers = S.getprop(spec, "headers")
+
+        headers =
+          if headers == nil do
+            h = S.jm([])
+            S.setprop(spec, "headers", h)
+            h
+          else
+            headers
+          end
+
+        # Respect a key the caller already provided.
+        if F.header_get(headers, header) == nil do
+          key = genkey(f)
+          S.setprop(headers, header, key)
+
+          client = S.getprop(f, "client")
+          track = F.track_node(client, "_idempotency", S.jm(["issued", 0, "last", nil]))
+          S.setprop(track, "issued", S.getprop(track, "issued") + 1)
+          S.setprop(track, "last", key)
+        end
+      end
+    end
+
+    nil
+  end
+
+  defp mutating(f, ctx) do
+    opts = F.opts(f)
+    methods = opt_list(S.getprop(opts, "methods"), ["POST", "PUT", "PATCH", "DELETE"])
+
+    spec = S.getprop(ctx, "spec")
+
+    method =
+      if spec != nil and S.getprop(spec, "method") != nil do
+        String.upcase(to_string(S.getprop(spec, "method")))
+      else
+        ""
+      end
+
+    if method != "" and method in methods do
+      true
+    else
+      op = S.getprop(ctx, "op")
+      opname = if op != nil, do: S.getprop(op, "name"), else: nil
+      ops = opt_list(S.getprop(opts, "ops"), ["create", "update", "remove"])
+      opname in ops
+    end
+  end
+
+  defp genkey(f) do
+    kg = S.getprop(F.opts(f), "keygen")
+
+    if S.isfunc(kg) do
+      kg.()
+    else
+      :crypto.strong_rand_bytes(12) |> Base.encode16(case: :lower)
+    end
+  end
+
+  # Python `v or default`: falsy = nil, false, 0, 0.0, "".
+  defp por(v, d) do
+    if v == nil or v == false or v == 0 or v == "", do: d, else: v
+  end
+
+  # Struct list node -> plain Elixir list; nil/empty -> default.
+  defp opt_list(v, default) do
+    cond do
+      v == nil -> default
+      S.islist(v) and S.isempty(v) -> default
+      S.islist(v) -> Enum.map(0..(S.size(v) - 1), fn i -> S.getelem(v, i) end)
+      true -> default
+    end
+  end
+end

package/project/.sdk/tm/elixir/lib/projectname/feature/log.ex

@@ -0,0 +1,62 @@
+# ProjectName SDK log feature
+#
+# Logs each pipeline hook via an injectable logger (options.logger with
+# info/debug/warn/error functions), defaulting to stderr.
+
+defmodule ProjectName.Feature.Log do
+  alias Voxgig.Struct, as: S
+  alias ProjectName.Feature, as: F
+
+  @hooks ~w(PostConstruct PostConstructEntity SetData GetData SetMatch GetMatch
+            PrePoint PreSpec PreRequest PreResponse PreResult)
+
+  def new do
+    f = F.base("log")
+    F.install(f, "init", fn ctx, opts -> init(f, ctx, opts) end)
+
+    Enum.each(@hooks, fn hook ->
+      F.install(f, hook, fn ctx -> loghook(f, hook, ctx) end)
+    end)
+
+    f
+  end
+
+  def init(f, ctx, options) do
+    active = F.init_common(f, ctx, options)
+
+    if active do
+      logger = S.getprop(F.opts(f), "logger")
+
+      logger =
+        if S.ismap(logger) do
+          logger
+        else
+          mk = fn level ->
+            fn msg -> IO.write(:stderr, "[" <> level <> "] " <> msg <> "\n") end
+          end
+
+          S.jm(["info", mk.("INFO"), "debug", mk.("DEBUG"), "warn", mk.("WARN"), "error", mk.("ERROR")])
+        end
+
+      S.setprop(f, "logger", logger)
+    end
+
+    nil
+  end
+
+  defp loghook(f, hook, ctx) do
+    if F.active?(f) do
+      logger = S.getprop(f, "logger")
+
+      if logger != nil do
+        op = S.getprop(ctx, "op")
+        opname = if op != nil, do: S.getprop(op, "name"), else: ""
+        msg = "hook=" <> hook <> " op=" <> to_string(opname)
+        log_fn = S.getprop(logger, "info")
+        if S.isfunc(log_fn), do: log_fn.(msg)
+      end
+    end
+
+    nil
+  end
+end

package/project/.sdk/tm/elixir/lib/projectname/feature/metrics.ex

@@ -0,0 +1,130 @@
+# ProjectName SDK metrics feature
+#
+# 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.
+
+defmodule ProjectName.Feature.Metrics do
+  alias Voxgig.Struct, as: S
+  alias ProjectName.Feature, as: F
+
+  def new do
+    f = F.base("metrics")
+    F.install(f, "init", fn ctx, opts -> init(f, ctx, opts) end)
+    F.install(f, "PrePoint", fn ctx -> pre_point(f, ctx) end)
+    F.install(f, "PreDone", fn ctx -> pre_done(f, ctx) end)
+    F.install(f, "PreUnexpected", fn ctx -> pre_unexpected(f, ctx) end)
+    f
+  end
+
+  def init(f, ctx, options) do
+    F.init_common(f, ctx, options)
+
+    client = S.getprop(f, "client")
+
+    if S.getprop(client, "_metrics") == nil do
+      S.setprop(
+        client,
+        "_metrics",
+        S.jm([
+          "total", S.jm(["count", 0, "ok", 0, "err", 0, "totalMs", 0, "maxMs", 0]),
+          "ops", S.jm([])
+        ])
+      )
+    end
+
+    nil
+  end
+
+  defp pre_point(f, ctx) do
+    if not F.active?(f) do
+      nil
+    else
+      S.setprop(ctx, "_metrics_start", F.now(f))
+      nil
+    end
+  end
+
+  defp pre_done(f, ctx) do
+    if not F.active?(f) do
+      nil
+    else
+      # Classify by the actual result: a 4xx/5xx that flows through still
+      # reaches PreDone before the pipeline raises.
+      result = S.getprop(ctx, "result")
+      ok = result != nil and S.getprop(result, "ok") != false and S.getprop(result, "err") == nil
+      record(f, ctx, ok)
+    end
+  end
+
+  defp pre_unexpected(f, ctx) do
+    if not F.active?(f) do
+      nil
+    else
+      record(f, ctx, false)
+    end
+  end
+
+  # 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.
+  defp record(f, ctx, ok) do
+    start = S.getprop(ctx, "_metrics_start")
+
+    if start == nil do
+      nil
+    else
+      S.delprop(ctx, "_metrics_start")
+
+      dur = max(0, F.now(f) - start)
+
+      metrics = S.getprop(S.getprop(f, "client"), "_metrics")
+      op = S.getprop(ctx, "op")
+
+      key =
+        if op != nil do
+          por(S.getprop(op, "entity"), "_") <> "." <> por(S.getprop(op, "name"), "_")
+        else
+          "_"
+        end
+
+      ops = S.getprop(metrics, "ops")
+      op_bucket = S.getprop(ops, key)
+
+      op_bucket =
+        if op_bucket == nil do
+          b = S.jm(["count", 0, "ok", 0, "err", 0, "totalMs", 0, "maxMs", 0])
+          S.setprop(ops, key, b)
+          b
+        else
+          op_bucket
+        end
+
+      bump(S.getprop(metrics, "total"), ok, dur)
+      bump(op_bucket, ok, dur)
+      nil
+    end
+  end
+
+  defp bump(bucket, ok, dur) do
+    S.setprop(bucket, "count", S.getprop(bucket, "count") + 1)
+
+    ok_key = if ok, do: "ok", else: "err"
+    S.setprop(bucket, ok_key, S.getprop(bucket, ok_key) + 1)
+
+    S.setprop(bucket, "totalMs", S.getprop(bucket, "totalMs") + dur)
+
+    if dur > S.getprop(bucket, "maxMs") do
+      S.setprop(bucket, "maxMs", dur)
+    end
+
+    nil
+  end
+
+  # Python `v or default`: falsy = nil, false, "".
+  defp por(v, d) do
+    if v == nil or v == false or v == "", do: d, else: v
+  end
+end

package/project/.sdk/tm/elixir/lib/projectname/feature/netsim.ex

@@ -0,0 +1,213 @@
+# ProjectName SDK netsim feature
+#
+# 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.
+
+defmodule ProjectName.Feature.Netsim do
+  alias Voxgig.Struct, as: S
+  alias ProjectName.Helpers, as: H
+  alias ProjectName.{Feature, Context}
+
+  def new do
+    f = Feature.base("netsim")
+    S.setprop(f, "calls", 0)
+    S.setprop(f, "seed", 1)
+    Feature.install(f, "init", fn ctx, opts -> init(f, ctx, opts) end)
+    f
+  end
+
+  def init(f, ctx, options) do
+    active = Feature.init_common(f, ctx, options)
+
+    seed_opt = S.getprop(Feature.opts(f), "seed")
+
+    seed =
+      if is_number(seed_opt) and not is_boolean(seed_opt) and trunc(seed_opt) != 0 do
+        trunc(seed_opt)
+      else
+        1
+      end
+
+    S.setprop(f, "seed", seed)
+
+    if active do
+      utility = S.getprop(ctx, "utility")
+      inner = S.getprop(utility, "fetcher")
+
+      S.setprop(utility, "fetcher", fn fctx, fullurl, fetchdef ->
+        simulate(f, fctx, fullurl, fetchdef, inner)
+      end)
+    end
+
+    nil
+  end
+
+  defp simulate(f, ctx, url, fetchdef, inner) do
+    opts = Feature.opts(f)
+    call = S.getprop(f, "calls") + 1
+    S.setprop(f, "calls", call)
+
+    # Record the simulated conditions for test/debug inspection.
+    applied = S.jm([])
+
+    cond do
+      # Total outage: every call fails at the transport level.
+      S.getprop(opts, "offline") == true ->
+        Feature.sleep(f, pick_latency(f))
+        S.setprop(applied, "offline", true)
+        track(f, ctx, applied)
+
+        {nil,
+         Context.make_error(
+           ctx,
+           "netsim_offline",
+           "Simulated network offline (URL was: \"" <> url <> "\")"
+         )}
+
+      # Connection-level errors for the first N calls (e.g. ECONNRESET).
+      call <= int_or0(S.getprop(opts, "errorTimes")) ->
+        Feature.sleep(f, pick_latency(f))
+        S.setprop(applied, "error", true)
+        track(f, ctx, applied)
+
+        {nil,
+         Context.make_error(
+           ctx,
+           "netsim_conn",
+           "Simulated connection error (call " <> Integer.to_string(call) <> ")"
+         )}
+
+      # Rate-limit responses (HTTP 429 + Retry-After) for the first N calls.
+      call <= int_or0(S.getprop(opts, "rateLimitTimes")) ->
+        Feature.sleep(f, pick_latency(f))
+        S.setprop(applied, "rateLimited", true)
+        track(f, ctx, applied)
+
+        ra = S.getprop(opts, "retryAfter")
+        ra = if ra == nil, do: 0, else: ra
+
+        ra_str =
+          cond do
+            is_binary(ra) -> ra
+            is_number(ra) -> to_string(ra)
+            true -> S.stringify(ra)
+          end
+
+        respond(ctx, 429, nil,
+          S.jm(["statusText", "Too Many Requests", "headers", S.jm(["retry-after", ra_str])]))
+
+      # Retryable failure status for the first N calls, or every Nth call.
+      true ->
+        fs = S.getprop(opts, "failStatus")
+        fail_status = if fs == nil, do: 503, else: fs
+        fail_every = int_or0(S.getprop(opts, "failEvery"))
+        fr = S.getprop(opts, "failRate")
+        fail_rate = if pytrue?(fr), do: fr, else: 0
+        fail_by_count = call <= int_or0(S.getprop(opts, "failTimes"))
+        fail_by_every = fail_every > 0 and rem(call, fail_every) == 0
+        fail_by_rate = fail_rate > 0 and rand(f) < fail_rate
+
+        if fail_by_count or fail_by_every or fail_by_rate do
+          Feature.sleep(f, pick_latency(f))
+          S.setprop(applied, "failStatus", fail_status)
+          track(f, ctx, applied)
+          respond(ctx, fail_status, nil, S.jm(["statusText", "Simulated Failure"]))
+        else
+          # Otherwise: apply latency then delegate to the real transport.
+          latency = pick_latency(f)
+          S.setprop(applied, "latency", latency)
+          track(f, ctx, applied)
+          Feature.sleep(f, latency)
+          inner.(ctx, url, fetchdef)
+        end
+    end
+  end
+
+  # Latency in ms: a fixed number, or a uniform sample from {min,max}.
+  defp pick_latency(f) do
+    latency = S.getprop(Feature.opts(f), "latency")
+
+    cond do
+      latency == nil ->
+        0
+
+      is_number(latency) and not is_boolean(latency) ->
+        if latency < 0, do: 0, else: latency
+
+      not S.ismap(latency) ->
+        0
+
+      true ->
+        mn = int_or0(S.getprop(latency, "min"))
+        maxv = S.getprop(latency, "max")
+        mx = if maxv == nil, do: mn, else: int_or0(maxv)
+        if mx <= mn, do: mn, else: mn + trunc(rand(f) * (mx - mn))
+    end
+  end
+
+  # Deterministic 0..1 pseudo-random via a linear congruential generator.
+  defp rand(f) do
+    seed = Bitwise.band(S.getprop(f, "seed") * 1103515245 + 12345, 0x7FFFFFFF)
+    S.setprop(f, "seed", seed)
+    seed / 0x7FFFFFFF
+  end
+
+  defp track(f, ctx, applied) do
+    client = S.getprop(f, "client")
+    t = Feature.track_node(client, "_netsim", S.jm(["calls", 0, "applied", S.jt([])]))
+    S.setprop(t, "calls", S.getprop(t, "calls") + 1)
+    Feature.list_push(S.getprop(t, "applied"), applied)
+
+    ctrl = S.getprop(ctx, "ctrl")
+    explain = if ctrl != nil, do: S.getprop(ctrl, "explain"), else: nil
+    if S.ismap(explain), do: S.setprop(explain, "netsim", t)
+    nil
+  end
+
+  # Build a transport-shaped response (matching the test feature's mock)
+  # with a lower-cased header map the result pipeline understands.
+  defp respond(_ctx, status, data, extra) do
+    out =
+      S.jm([
+        "status", status,
+        "statusText", "OK",
+        "json", fn -> data end,
+        "body", "not-used"
+      ])
+
+    if S.ismap(extra) do
+      Enum.each(H.entries(extra), fn {k, v} -> S.setprop(out, k, v) end)
+    end
+
+    headers = S.getprop(out, "headers")
+    headers = if S.ismap(headers), do: headers, else: S.jm([])
+
+    lower = S.jm([])
+    Enum.each(H.entries(headers), fn {k, v} -> S.setprop(lower, String.downcase(to_string(k)), v) end)
+    S.setprop(out, "headers", lower)
+
+    {out, nil}
+  end
+
+  # Mirrors Python `int(x or 0)`: falsey -> 0, then integer-truncate.
+  defp int_or0(v) do
+    cond do
+      is_integer(v) -> v
+      is_number(v) -> trunc(v)
+      is_binary(v) -> (case Integer.parse(v) do
+                         {n, _} -> n
+                         _ -> 0
+                       end)
+      true -> 0
+    end
+  end
+
+  # Python truthiness (nil / false / "" / 0 are falsey).
+  defp pytrue?(v), do: not (v == nil or v == false or v == "" or v == 0)
+end

package/project/.sdk/tm/elixir/lib/projectname/feature/paging.ex

@@ -0,0 +1,191 @@
+# ProjectName SDK paging feature
+#
+# 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.
+
+defmodule ProjectName.Feature.Paging do
+  alias Voxgig.Struct, as: S
+  alias ProjectName.Feature, as: F
+
+  @next_re ~r/<([^>]+)>\s*;\s*rel="?next"?/i
+
+  def new do
+    f = F.base("paging")
+    F.install(f, "init", fn ctx, opts -> init(f, ctx, opts) end)
+    F.install(f, "PreRequest", fn ctx -> pre_request(f, ctx) end)
+    F.install(f, "PreResult", fn ctx -> pre_result(f, ctx) end)
+    f
+  end
+
+  def init(f, ctx, options) do
+    F.init_common(f, ctx, options)
+    nil
+  end
+
+  defp pre_request(f, ctx) do
+    if F.active?(f) and is_list_op(f, ctx) do
+      spec = S.getprop(ctx, "spec")
+
+      if spec != nil do
+        query =
+          case S.getprop(spec, "query") do
+            nil ->
+              q = S.jm([])
+              S.setprop(spec, "query", q)
+              q
+
+            q ->
+              q
+          end
+
+        opts = F.opts(f)
+        page_param = por(S.getprop(opts, "pageParam"), "page")
+        limit_param = por(S.getprop(opts, "limitParam"), "limit")
+        cursor_param = por(S.getprop(opts, "cursorParam"), "cursor")
+
+        # A per-call cursor/page from ctrl takes priority (auto-iteration).
+        ctrl = S.getprop(ctx, "ctrl")
+        paging = if ctrl != nil, do: S.getprop(ctrl, "paging"), else: nil
+        paging = if S.ismap(paging), do: paging, else: S.jm([])
+
+        cond do
+          S.getprop(paging, "cursor") != nil ->
+            S.setprop(query, cursor_param, S.getprop(paging, "cursor"))
+
+          S.getprop(query, page_param) == nil ->
+            page = S.getprop(paging, "page")
+            page = if page == nil, do: por(S.getprop(opts, "startPage"), 1), else: page
+            S.setprop(query, page_param, page)
+
+          true ->
+            nil
+        end
+
+        limit = S.getprop(opts, "limit")
+
+        if limit != nil and S.getprop(query, limit_param) == nil do
+          S.setprop(query, limit_param, limit)
+        end
+      end
+    end
+
+    nil
+  end
+
+  defp pre_result(f, ctx) do
+    if F.active?(f) and is_list_op(f, ctx) do
+      result = S.getprop(ctx, "result")
+
+      if result != nil do
+        headers = S.getprop(result, "headers")
+        headers = if headers == nil, do: S.jm([]), else: headers
+        body = S.getprop(result, "body")
+
+        page = num(F.header_get(headers, "x-page"))
+        total_count = num(F.header_get(headers, "x-total-count"))
+        next_page = num(F.header_get(headers, "x-next-page"))
+
+        # Link: <...>; rel="next"
+        link = F.header_get(headers, "link")
+
+        next_from_link =
+          if link != nil do
+            case Regex.run(@next_re, to_string(link)) do
+              [_, url] -> url
+              _ -> nil
+            end
+          else
+            nil
+          end
+
+        {next_val, cursor_val, has_more} =
+          if S.ismap(body) do
+            n =
+              case S.getprop(body, "next") do
+                nil -> next_from_link
+                bnext -> por(next_from_link, bnext)
+              end
+
+            c =
+              cond do
+                S.getprop(body, "nextCursor") != nil -> S.getprop(body, "nextCursor")
+                S.getprop(body, "cursor") != nil -> S.getprop(body, "cursor")
+                true -> nil
+              end
+
+            hm =
+              case S.getprop(body, "hasMore") do
+                v when is_boolean(v) -> v
+                _ -> false
+              end
+
+            {n, c, hm}
+          else
+            {next_from_link, nil, false}
+          end
+
+        has_more =
+          has_more or next_val != nil or cursor_val != nil or next_page != nil
+
+        paging =
+          S.jm([
+            "page", page,
+            "totalCount", total_count,
+            "nextPage", next_page,
+            "next", next_val,
+            "cursor", cursor_val,
+            "hasMore", has_more
+          ])
+
+        S.setprop(result, "paging", paging)
+        S.setprop(S.getprop(f, "client"), "_paging", S.jm(["last", paging]))
+      end
+    end
+
+    nil
+  end
+
+  defp is_list_op(f, ctx) do
+    ops = opt_list(S.getprop(F.opts(f), "ops"), ["list"])
+    op = S.getprop(ctx, "op")
+    opname = if op != nil, do: S.getprop(op, "name"), else: nil
+    opname in ops
+  end
+
+  # Parse a numeric header value: int when integral, float otherwise, nil when
+  # not a full number (mirrors Python float()/int() with ValueError -> None).
+  defp num(val) do
+    if val == nil do
+      nil
+    else
+      s = String.trim(to_string(val))
+
+      case Float.parse(s) do
+        {n, ""} -> if n == trunc(n), do: trunc(n), else: n
+        _ -> nil
+      end
+    end
+  end
+
+  # Python `v or default`: falsy = nil, false, 0, 0.0, "".
+  defp por(v, d) do
+    if v == nil or v == false or v == 0 or v == "", do: d, else: v
+  end
+
+  # Struct list node -> plain Elixir list; nil/empty -> default.
+  defp opt_list(v, default) do
+    cond do
+      v == nil -> default
+      S.islist(v) and S.isempty(v) -> default
+      S.islist(v) -> Enum.map(0..(S.size(v) - 1), fn i -> S.getelem(v, i) end)
+      true -> default
+    end
+  end
+end