@voxgig/sdkgen 1.3.7 → 1.3.9

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

@@ -0,0 +1,172 @@
+# ProjectName SDK telemetry feature
+#
+# Distributed-tracing telemetry. Opens a span per operation (PrePoint),
+# propagates trace context to the server as W3C `traceparent` plus
+# `X-Trace-Id` / `X-Span-Id` headers (PreRequest), and closes the span on
+# completion (PreDone) or failure (PreUnexpected). Finished spans are kept
+# on `client._telemetry["spans"]`; an `exporter` callback, when provided,
+# is invoked with each finished span. Trace/span id generation (`idgen`)
+# and the clock (`now`) are injectable for deterministic tests.
+
+defmodule ProjectName.Feature.Telemetry do
+  alias Voxgig.Struct, as: S
+  alias ProjectName.Helpers, as: H
+  alias ProjectName.Feature, as: F
+
+  def new do
+    f = F.base("telemetry")
+    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, "PreRequest", fn ctx -> pre_request(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)
+    S.setprop(f, "seq", 0)
+
+    client = S.getprop(f, "client")
+
+    if S.getprop(client, "_telemetry") == nil do
+      S.setprop(client, "_telemetry", S.jm(["spans", S.jt([]), "active", 0]))
+    end
+
+    nil
+  end
+
+  defp pre_point(f, ctx) do
+    if not F.active?(f) do
+      nil
+    else
+      op = S.getprop(ctx, "op")
+
+      {entity, opname} =
+        if op != nil do
+          {por(S.getprop(op, "entity"), "_"), por(S.getprop(op, "name"), "_")}
+        else
+          {"_", "_"}
+        end
+
+      span =
+        S.jm([
+          "traceId", gen_id(f, "trace"),
+          "spanId", gen_id(f, "span"),
+          "name", entity <> "." <> opname,
+          "start", F.now(f),
+          "end", nil,
+          "durationMs", nil,
+          "ok", nil
+        ])
+
+      S.setprop(ctx, "_telemetry_span", span)
+
+      telemetry = S.getprop(S.getprop(f, "client"), "_telemetry")
+      S.setprop(telemetry, "active", S.getprop(telemetry, "active") + 1)
+      nil
+    end
+  end
+
+  defp pre_request(f, ctx) do
+    if not F.active?(f) do
+      nil
+    else
+      span = S.getprop(ctx, "_telemetry_span")
+      spec = S.getprop(ctx, "spec")
+
+      if span == nil or spec == nil do
+        nil
+      else
+        if S.getprop(spec, "headers") == nil do
+          S.setprop(spec, "headers", S.jm([]))
+        end
+
+        headers = S.getprop(spec, "headers")
+        hopt = H.or_(H.to_map(S.getprop(F.opts(f), "headers")), S.jm([]))
+
+        S.setprop(headers, por(S.getprop(hopt, "trace"), "X-Trace-Id"), S.getprop(span, "traceId"))
+        S.setprop(headers, por(S.getprop(hopt, "span"), "X-Span-Id"), S.getprop(span, "spanId"))
+
+        S.setprop(
+          headers,
+          por(S.getprop(hopt, "parent"), "traceparent"),
+          "00-" <> S.getprop(span, "traceId") <> "-" <> S.getprop(span, "spanId") <> "-01"
+        )
+
+        nil
+      end
+    end
+  end
+
+  defp pre_done(f, ctx) do
+    if not F.active?(f) do
+      nil
+    else
+      result = S.getprop(ctx, "result")
+      ok = result != nil and S.getprop(result, "ok") != false and S.getprop(result, "err") == nil
+      close(f, ctx, ok)
+    end
+  end
+
+  defp pre_unexpected(f, ctx) do
+    if not F.active?(f) do
+      nil
+    else
+      close(f, ctx, false)
+    end
+  end
+
+  # Close once per operation; a PreDone followed by a pipeline raise (non-2xx)
+  # fires PreUnexpected too, which then finds no open span.
+  defp close(f, ctx, ok) do
+    span = S.getprop(ctx, "_telemetry_span")
+
+    if span == nil do
+      nil
+    else
+      S.delprop(ctx, "_telemetry_span")
+
+      fin = F.now(f)
+      S.setprop(span, "end", fin)
+      S.setprop(span, "durationMs", max(0, fin - S.getprop(span, "start")))
+      S.setprop(span, "ok", ok)
+
+      telemetry = S.getprop(S.getprop(f, "client"), "_telemetry")
+      S.setprop(telemetry, "active", S.getprop(telemetry, "active") - 1)
+      F.list_push(S.getprop(telemetry, "spans"), span)
+
+      exporter = S.getprop(F.opts(f), "exporter")
+
+      if S.isfunc(exporter) do
+        try do
+          exporter.(span)
+        rescue
+          _ -> nil
+        end
+      end
+
+      nil
+    end
+  end
+
+  defp gen_id(f, kind) do
+    idgen = S.getprop(F.opts(f), "idgen")
+
+    if S.isfunc(idgen) do
+      idgen.(kind)
+    else
+      # Deterministic-ish sequential id; unique within a client instance.
+      seq = S.getprop(f, "seq") + 1
+      S.setprop(f, "seq", seq)
+      n = seq |> Integer.to_string(16) |> String.downcase() |> String.pad_leading(4, "0")
+      prefix = if kind == "trace", do: "t", else: "s"
+      prefix <> String.pad_trailing(n, 16, "0")
+    end
+  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/test.ex

@@ -0,0 +1,285 @@
+# ProjectName SDK test feature
+#
+# In-memory mock transport for offline tests. Installs a fetcher that
+# resolves ops against a per-entity data store (from options.entity) using
+# the vendored struct select/transform engine — the same query shaping as
+# the live SDK. An optional `net` block simulates latency/failures.
+
+defmodule ProjectName.Feature.Test do
+  alias Voxgig.Struct, as: S
+  alias ProjectName.Helpers, as: H
+  alias ProjectName.{Feature, Context, Utility}
+
+  def new do
+    f = Feature.base("test")
+    Feature.install(f, "init", fn ctx, opts -> init(f, ctx, opts) end)
+    f
+  end
+
+  def init(f, ctx, options) do
+    Feature.init_common(f, ctx, options)
+    opts = Feature.opts(f)
+
+    entity = S.getprop(opts, "entity")
+    entity = if S.ismap(entity), do: entity, else: S.jm([])
+
+    S.setprop(S.getprop(ctx, "client"), "mode", "test")
+
+    # Ensure entity records carry their id (the map key).
+    S.walk(entity,
+      before: fn key, val, _parent, path ->
+        if S.size(path) == 2 and S.ismap(val) and key != nil, do: S.setprop(val, "id", key)
+        val
+      end
+    )
+
+    test_fetcher = fn fctx, _url, _fetchdef -> respond_op(f, entity, fctx) end
+
+    utility = S.getprop(ctx, "utility")
+    net = S.getprop(opts, "net")
+
+    if S.ismap(net) do
+      S.setprop(utility, "fetcher", make_netsim(f, net, test_fetcher))
+    else
+      S.setprop(utility, "fetcher", test_fetcher)
+    end
+
+    nil
+  end
+
+  defp respond(status, data, extra \\ nil) 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
+
+    {out, nil}
+  end
+
+  defp resolve_match(fctx, explicit) do
+    if S.ismap(explicit) and S.size(explicit) > 0 do
+      explicit
+    else
+      Enum.find_value([S.getprop(fctx, "match"), S.getprop(fctx, "data")], S.jm([]), fn src ->
+        v = if src != nil, do: S.getprop(src, "id"), else: nil
+        if v != nil and v != "__UNDEFINED__", do: S.jm(["id", v])
+      end)
+    end
+  end
+
+  defp respond_op(f, entity, fctx) do
+    op = S.getprop(fctx, "op")
+    opname = S.getprop(op, "name")
+    entmap = S.getprop(entity, S.getprop(op, "entity"))
+    entmap = if S.ismap(entmap), do: entmap, else: S.jm([])
+
+    case opname do
+      "load" ->
+        args = build_args(f, fctx, op, resolve_match(fctx, S.getprop(fctx, "reqmatch")))
+        found = S.select(entmap, args)
+        ent = S.getelem(found, 0)
+
+        if ent == nil do
+          respond(404, nil, S.jm(["statusText", "Not found"]))
+        else
+          S.delprop(ent, "$KEY")
+          respond(200, S.clone(ent))
+        end
+
+      "list" ->
+        args = build_args(f, fctx, op, S.getprop(fctx, "reqmatch"))
+        found = S.select(entmap, args)
+
+        if found == nil do
+          respond(404, nil, S.jm(["statusText", "Not found"]))
+        else
+          if S.islist(found) and S.size(found) > 0 do
+            Enum.each(0..(S.size(found) - 1), fn i -> S.delprop(S.getelem(found, i), "$KEY") end)
+          end
+
+          respond(200, S.clone(found))
+        end
+
+      "update" ->
+        reqdata = S.getprop(fctx, "reqdata")
+
+        update_match =
+          if S.ismap(reqdata) do
+            um = S.jm([])
+            if S.getprop(reqdata, "id") != nil, do: S.setprop(um, "id", S.getprop(reqdata, "id"))
+            alias_map = S.getprop(op, "alias")
+
+            if alias_map != nil do
+              alias_id = S.getprop(alias_map, "id")
+
+              if alias_id != nil and S.getprop(reqdata, alias_id) != nil do
+                S.setprop(um, alias_id, S.getprop(reqdata, alias_id))
+              end
+            end
+
+            um
+          else
+            S.jm([])
+          end
+
+        update_match = if S.size(update_match) == 0, do: resolve_match(fctx, S.jm([])), else: update_match
+        args = build_args(f, fctx, op, update_match)
+        found = S.select(entmap, args)
+        ent = S.getelem(found, 0)
+
+        ent =
+          if ent == nil and S.ismap(entmap) do
+            ks = S.keysof(entmap)
+            Enum.find_value(ks, fn k -> v = S.getprop(entmap, k); if S.ismap(v), do: v end)
+          else
+            ent
+          end
+
+        if ent == nil do
+          respond(404, nil, S.jm(["statusText", "Not found"]))
+        else
+          if S.ismap(ent) and reqdata != nil do
+            Enum.each(H.entries(reqdata), fn {k, v} -> S.setprop(ent, k, v) end)
+          end
+
+          S.delprop(ent, "$KEY")
+          respond(200, S.clone(ent))
+        end
+
+      "remove" ->
+        args = build_args(f, fctx, op, resolve_match(fctx, S.getprop(fctx, "reqmatch")))
+        found = S.select(entmap, args)
+        ent = S.getelem(found, 0)
+
+        if S.ismap(ent) do
+          eid = S.getprop(ent, "id")
+          S.delprop(entmap, eid)
+        end
+
+        respond(200, nil)
+
+      "create" ->
+        build_args(f, fctx, op, S.getprop(fctx, "reqdata"))
+        eid = Utility.param(fctx, "id")
+        eid = if eid == nil, do: gen_id(), else: eid
+        ent = S.clone(S.getprop(fctx, "reqdata"))
+
+        if S.ismap(ent) do
+          S.setprop(ent, "id", eid)
+          if is_binary(eid), do: S.setprop(entmap, eid, ent)
+          S.delprop(ent, "$KEY")
+          respond(200, S.clone(ent))
+        else
+          respond(200, ent)
+        end
+
+      _ ->
+        respond(404, nil, S.jm(["statusText", "Unknown operation"]))
+    end
+  end
+
+  defp gen_id do
+    :crypto.strong_rand_bytes(8) |> Base.encode16(case: :lower)
+  end
+
+  # Build a struct select query ($AND of $OR alternatives) from the required
+  # params + id, resolving each value through the pipeline param resolver.
+  def build_args(_f, ctx, op, args) do
+    opname = S.getprop(op, "name")
+    config = S.getprop(ctx, "config")
+    entname = Context.entity_name(S.getprop(ctx, "entity"))
+    points = S.getpath(config, "entity." <> entname <> ".op." <> opname <> ".points")
+    point = S.getelem(points, -1)
+    params_path = S.getpath(point, "args.params")
+    reqd_params = S.select(params_path, S.jm(["reqd", true]))
+    reqd = S.transform(reqd_params, S.jt(["`$EACH`", "", "`$KEY.name`"]))
+
+    qand = S.jt([])
+    q = S.jm(["`$AND`", qand])
+
+    if args != nil do
+      Enum.each(S.keysof(args), fn key ->
+        is_id = key == "id"
+        selected = S.select(reqd, key)
+        is_reqd = not S.isempty(selected)
+
+        if is_id or is_reqd do
+          v = Utility.param(ctx, key)
+          ka = if S.getprop(op, "alias") != nil, do: S.getprop(S.getprop(op, "alias"), key), else: nil
+
+          qor = S.jt([S.jm([key, v])])
+          if is_binary(ka), do: Feature.list_push(qor, S.jm([ka, v]))
+
+          Feature.list_push(qand, S.jm(["`$OR`", qor]))
+        end
+      end)
+    end
+
+    ctrl = S.getprop(ctx, "ctrl")
+    explain = if ctrl != nil, do: S.getprop(ctrl, "explain"), else: nil
+    if explain != nil, do: S.setprop(explain, "test", S.jm(["query", q]))
+
+    q
+  end
+
+  # Counter-driven network simulation over the mock transport.
+  defp make_netsim(f, net, inner) do
+    S.setprop(f, "_netcalls", 0)
+
+    # Injectable sleep lives in the `net` block (net.sleep), not feature opts.
+    netsleep = fn ms ->
+      if ms != nil and ms > 0 do
+        ns = S.getprop(net, "sleep")
+        if S.isfunc(ns), do: ns.(ms), else: :timer.sleep(trunc(ms))
+      end
+    end
+
+    fn fctx, url, fetchdef ->
+      call = S.getprop(f, "_netcalls") + 1
+      S.setprop(f, "_netcalls", call)
+
+      cond do
+        S.getprop(net, "offline") == true ->
+          netsleep.(pick_latency(net))
+          {nil, Context.make_error(fctx, "netsim_offline", "Simulated network offline (URL was: \"" <> url <> "\")")}
+
+        call <= H.to_int(H.or_(S.getprop(net, "errorTimes"), 0)) ->
+          netsleep.(pick_latency(net))
+          {nil, Context.make_error(fctx, "netsim_conn", "Simulated connection error (call " <> Integer.to_string(call) <> ")")}
+
+        call <= H.to_int(H.or_(S.getprop(net, "failTimes"), 0)) ->
+          netsleep.(pick_latency(net))
+          status = H.or_(S.getprop(net, "failStatus"), 503)
+
+          respond(status, nil,
+            S.jm(["statusText", "Simulated Failure", "headers", S.jm([])]))
+
+        true ->
+          netsleep.(pick_latency(net))
+          inner.(fctx, url, fetchdef)
+      end
+    end
+  end
+
+  defp pick_latency(net) do
+    latency = S.getprop(net, "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 = H.to_int(H.or_(S.getprop(latency, "min"), 0))
+        mxv = S.getprop(latency, "max")
+        mx = if mxv == nil, do: mn, else: H.to_int(mxv)
+        if mx <= mn, do: mn, else: mn + div(mx - mn, 2)
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# ProjectName SDK timeout feature
+#
+# Per-request timeout. Wraps the active transport with a deadline of `ms`
+# milliseconds (default 30000; <= 0 disables). The fetch definition is
+# annotated with a `timeout` (in seconds, for transports that honour it) and
+# the elapsed time of each attempt is checked against the deadline; when the
+# deadline is exceeded the request resolves to a `timeout` error instead of a
+# late response. The clock (`now`) is injectable for deterministic tests.
+
+defmodule ProjectName.Feature.Timeout do
+  alias Voxgig.Struct, as: S
+  alias ProjectName.Feature, as: F
+  alias ProjectName.Context
+
+  def new do
+    f = F.base("timeout")
+    F.install(f, "init", fn ctx, opts -> init(f, ctx, opts) end)
+    f
+  end
+
+  def init(f, ctx, options) do
+    active = F.init_common(f, ctx, options)
+
+    if active do
+      utility = S.getprop(ctx, "utility")
+      inner = S.getprop(utility, "fetcher")
+      S.setprop(utility, "fetcher", fn fctx, url, fd -> with_timeout(f, fctx, url, fd, inner) end)
+    end
+
+    nil
+  end
+
+  defp with_timeout(f, ctx, url, fetchdef, inner) do
+    opts = F.opts(f)
+    ms = case S.getprop(opts, "ms") do nil -> 30000; v -> v end
+
+    if ms <= 0 do
+      inner.(ctx, url, fetchdef)
+    else
+      # Annotate the fetch definition so a real transport can cancel itself
+      # (Python-idiomatic analog of an abort signal). Copy so the caller's
+      # fetchdef is not mutated.
+      fetchdef = if S.ismap(fetchdef), do: S.clone(fetchdef), else: S.jm([])
+      S.setprop(fetchdef, "timeout", ms / 1000)
+
+      start = F.now(f)
+      {res, err} = inner.(ctx, url, fetchdef)
+      elapsed = F.now(f) - start
+
+      if elapsed > ms do
+        track(f, ms)
+        {nil, Context.make_error(ctx, "timeout", "Request exceeded timeout of " <> to_string(ms) <> "ms")}
+      else
+        {res, err}
+      end
+    end
+  end
+
+  defp track(f, ms) do
+    client = S.getprop(f, "client")
+    track = F.track_node(client, "_timeout", S.jm(["count", 0, "ms", ms]))
+    S.setprop(track, "count", S.getprop(track, "count") + 1)
+  end
+end

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

@@ -0,0 +1,90 @@
+# ProjectName SDK feature base + shared helpers.
+#
+# A feature instance is a reference-stable struct map node carrying its
+# name/version/active/options plus any per-instance state, and a member
+# closure per hook it implements (keyed by hook name — PreRequest, PrePoint,
+# ...). feature_hook dispatches by reading `getprop(f, name)` and calling it
+# when it is a function, so a feature only installs the hooks it needs (a
+# base feature installs none — the no-op equivalent of the donor base).
+
+defmodule ProjectName.Feature do
+  alias Voxgig.Struct, as: S
+  alias ProjectName.Helpers, as: H
+
+  # Base node: name, version, active(true), empty options.
+  def base(name, version \\ "0.0.1") do
+    f = S.jm([])
+    S.setprop(f, "name", name)
+    S.setprop(f, "version", version)
+    S.setprop(f, "active", true)
+    S.setprop(f, "options", S.jm([]))
+    f
+  end
+
+  def install(f, name, fun), do: S.setprop(f, name, fun)
+
+  def get_name(f), do: S.getprop(f, "name")
+
+  def new, do: base("base")
+
+  # options accessor
+  def opts(f), do: H.or_(S.getprop(f, "options"), S.jm([]))
+
+  # Set active from options.active == true (the common init prologue).
+  def init_common(f, ctx, options) do
+    S.setprop(f, "client", S.getprop(ctx, "client"))
+    o = if S.ismap(options), do: options, else: S.jm([])
+    S.setprop(f, "options", o)
+    active = S.getprop(o, "active") == true
+    S.setprop(f, "active", active)
+    active
+  end
+
+  def active?(f), do: S.getprop(f, "active") == true
+
+  # Injectable clock (ms) — options.now() when a function, else wall clock.
+  def now(f) do
+    n = S.getprop(opts(f), "now")
+    if S.isfunc(n), do: n.(), else: System.system_time(:millisecond)
+  end
+
+  # Injectable sleep — options.sleep(ms) when a function, else real sleep.
+  def sleep(f, ms) do
+    if ms != nil and ms > 0 do
+      s = S.getprop(opts(f), "sleep")
+      if S.isfunc(s), do: s.(ms), else: :timer.sleep(trunc(ms))
+    end
+
+    nil
+  end
+
+  # Push onto a struct list node (append).
+  def list_push(vlist, val), do: S.setprop(vlist, S.size(vlist), val)
+
+  # Get-or-create a tracking node on the client under `key`.
+  def track_node(client, key, init_node) do
+    t = S.getprop(client, key)
+
+    if t == nil do
+      S.setprop(client, key, init_node)
+      init_node
+    else
+      t
+    end
+  end
+
+  # Case-insensitive header lookup, nil when absent.
+  def header_get(headers, name) do
+    lower = String.downcase(name)
+
+    Enum.find_value(H.entries(headers), fn {k, v} ->
+      if String.downcase(to_string(k)) == lower, do: v
+    end)
+  end
+
+  # Case-insensitive presence test.
+  def header_has?(headers, name) do
+    lower = String.downcase(name)
+    Enum.any?(H.entries(headers), fn {k, _v} -> String.downcase(to_string(k)) == lower end)
+  end
+end

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

@@ -0,0 +1,66 @@
+# ProjectName SDK helpers
+#
+# Shared value helpers built on the vendored struct value type. Every SDK
+# runtime object (context, spec, result, response, control, operation,
+# utility, features, the client itself) is a reference-stable struct map
+# node ({:vmap, id}, ETS-backed) so that a feature hook mutating the node
+# is observed by every later pipeline stage that holds the same reference
+# — the immutable-Elixir way to honour the shared-mutable hook contract.
+
+defmodule ProjectName.Helpers do
+  alias Voxgig.Struct, as: S
+
+  # Return v when it is a struct map node, else nil (mirrors py to_map).
+  def to_map(v), do: if(S.ismap(v), do: v, else: nil)
+
+  def to_int(v) when is_integer(v), do: v
+  def to_int(v) when is_float(v), do: trunc(v)
+  def to_int(_), do: -1
+
+  # Read a key from a struct map node, nil when the map/key is absent.
+  def get_ctx_prop(m, key), do: if(S.ismap(m), do: S.getprop(m, key), else: nil)
+
+  # Insertion-ordered {k, v} pairs of a struct map node as a plain Elixir
+  # list (struct keysof sorts; several pipeline steps need source order).
+  def entries(node) do
+    it = S.items(node)
+    n = S.size(it)
+    if n == 0 do
+      []
+    else
+      Enum.map(0..(n - 1), fn i ->
+        p = S.getelem(it, i)
+        {S.getelem(p, 0), S.getelem(p, 1)}
+      end)
+    end
+  end
+
+  # Deep-convert a native Elixir term (maps/lists/scalars, incl. function
+  # values) into struct nodes. Used by generated config and option specs.
+  def deep(v) do
+    cond do
+      is_map(v) and not is_struct(v) ->
+        S.jm(Enum.flat_map(v, fn {k, val} -> [to_string(k), deep(val)] end))
+
+      is_list(v) ->
+        S.jt(Enum.map(v, &deep/1))
+
+      true ->
+        v
+    end
+  end
+
+  # Truthy in the JS/py sense: nil and false are falsey, everything else
+  # (including 0 and "") is truthy — matches the donors' `or`/`if` idioms.
+  def truthy(nil), do: false
+  def truthy(false), do: false
+  def truthy(_), do: true
+
+  # First truthy value (JS `a || b`).
+  def or_(a, b), do: if(truthy(a), do: a, else: b)
+
+  def is_error(v), do: is_exception(v)
+
+  def str_or(v, d) when is_binary(v), do: if(v == "", do: d, else: v)
+  def str_or(_, d), do: d
+end