@voxgig/sdkgen 1.3.8 → 1.3.10

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/feature/RbacFeature.swift

@@ -0,0 +1,103 @@
+// Client-side role/permission enforcement. Before an operation resolves its
+// endpoint, the required permission for that entity+operation is checked
+// against the permissions the client holds; a disallowed call is
+// short-circuited with an `rbac_denied` error (via ctx.out["point"], which
+// makePoint surfaces) and never touches the network. Required permissions
+// come from `rules` (keyed by `<entity>.<op>`, `<op>`, or `*`); the default
+// when no rule matches is controlled by `deny` (default: allow when
+// unspecified). Held permissions are the `permissions` list (a `*` grants
+// everything).
+
+import Foundation
+
+public final class RbacFeature: BaseFeature {
+  private var client: ProjectNameSDK?
+  private var options: VMap?
+  private var granted: Set<String> = []
+
+  // Activity tracking (mirrors the ts client._rbac record).
+  public var allowed = 0
+  public var denied = 0
+  public var last: VMap?
+
+  public override init() {
+    super.init()
+    version = "0.0.1"
+    name = "rbac"
+    active = true
+  }
+
+  public override func initFeature(_ ctx: Context, _ options: VMap) {
+    client = ctx.client
+    self.options = options
+    active = foptBool(options, "active", false)
+
+    granted = []
+    for p in foptStrList(options, "permissions") ?? [] {
+      granted.insert(p)
+    }
+  }
+
+  public override func prePoint(_ ctx: Context) {
+    if !active {
+      return
+    }
+
+    let (required, has) = requiredPerm(ctx)
+    if !has {
+      // No rule: honour the default policy.
+      if foptBool(options, "deny", false) {
+        reject(ctx, "<default-deny>")
+      }
+      return
+    }
+
+    if granted.contains("*") || granted.contains(required) {
+      track(ctx, required, true)
+      return
+    }
+
+    reject(ctx, required)
+  }
+
+  private func requiredPerm(_ ctx: Context) -> (String, Bool) {
+    guard let rules = foptMap(options, "rules") else {
+      return ("", false)
+    }
+
+    let entity = ctx.entity?.getName() ?? ctx.op?.entity ?? ""
+    let opname = ctx.op?.name ?? ""
+
+    for key in [entity + "." + opname, opname, "*"] {
+      if let rs = gp(rules, key).asString {
+        return (rs, true)
+      }
+    }
+    return ("", false)
+  }
+
+  private func reject(_ ctx: Context, _ required: String) {
+    track(ctx, required, false)
+
+    let opname = ctx.op?.name ?? "?"
+    let err = ctx.makeError("rbac_denied",
+      "Permission \"" + required + "\" required for operation \"" + opname + "\"")
+
+    // Short-circuit endpoint resolution; makePoint surfaces this error
+    // before any network activity.
+    ctx.out["point"] = err
+  }
+
+  private func track(_ ctx: Context, _ required: String, _ isAllowed: Bool) {
+    if isAllowed {
+      allowed += 1
+    } else {
+      denied += 1
+    }
+    let l = VMap()
+    l.entries["required"] = .string(required)
+    l.entries["allowed"] = .bool(isAllowed)
+    l.entries["op"] = .string(ctx.op?.name ?? "")
+    last = l
+  }
+}

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/feature/RetryFeature.swift

@@ -0,0 +1,150 @@
+// Automatic retry of transient failures with exponential backoff and
+// jitter. Wraps the active transport so a single operation call may make
+// several HTTP attempts. A failure is retryable when the transport throws,
+// returns no value, or responds with a status in `statuses`
+// (default: 408, 425, 429, 500, 502, 503, 504). An HTTP 429/503 with a
+// `Retry-After` header overrides the computed backoff.
+
+import Foundation
+
+public final class RetryFeature: BaseFeature {
+  private var client: ProjectNameSDK?
+  private var options: VMap?
+
+  // Activity tracking (mirrors the ts client._retry record).
+  public var attempts = 0
+  public var retries: [VMap] = []
+
+  public override init() {
+    super.init()
+    version = "0.0.1"
+    name = "retry"
+    active = true
+  }
+
+  public override func initFeature(_ ctx: Context, _ options: VMap) {
+    client = ctx.client
+    self.options = options
+    active = foptBool(options, "active", false)
+
+    if !active {
+      return
+    }
+
+    let inner = ctx.utility!.fetcher!
+
+    ctx.utility!.fetcher = { ctx2, url, fetchdef in
+      try self.withRetry(ctx2, url, fetchdef, inner)
+    }
+  }
+
+  private func withRetry(_ ctx: Context, _ url: String, _ fetchdef: VMap,
+                         _ inner: FetcherFunc) throws -> Value {
+    let max = foptInt(options, "retries", 2)
+    let minDelay = foptInt(options, "minDelay", 50)
+    let maxDelay = foptInt(options, "maxDelay", 2000)
+    let factor = foptNum(options, "factor", 2)
+
+    var attempt = 0
+
+    while true {
+      var res: Value = .noval
+      var err: Error? = nil
+      do {
+        res = try inner(ctx, url, fetchdef)
+      } catch {
+        err = error
+      }
+
+      if !retryable(res, err) || attempt >= max {
+        // Out of attempts (or not retryable): return the last response as-is
+        // (or rethrow) to preserve pipeline semantics.
+        if let err = err {
+          throw err
+        }
+        return res
+      }
+
+      let wait = backoff(res, attempt, minDelay, maxDelay, factor)
+      track(attempt + 1, res, err, wait)
+      sleepMs(wait)
+      attempt += 1
+    }
+  }
+
+  private func retryable(_ res: Value, _ err: Error?) -> Bool {
+    if err != nil {
+      return true
+    }
+    if isNil(res) {
+      return true
+    }
+    let (status, has) = fresStatus(res)
+    if !has {
+      return false
+    }
+    let statuses: [Int]
+    if let list = foptList(options, "statuses") {
+      statuses = list.items.map { toInt($0) }
+    } else {
+      statuses = [408, 425, 429, 500, 502, 503, 504]
+    }
+    for s in statuses {
+      if s == status {
+        return true
+      }
+    }
+    return false
+  }
+
+  private func backoff(_ res: Value, _ attempt: Int, _ minDelay: Int, _ maxDelay: Int,
+                       _ factor: Double) -> Int {
+    // Honour a server-provided Retry-After (seconds) when present.
+    let (ra, has) = retryAfter(res)
+    if has {
+      return ra > maxDelay ? maxDelay : ra
+    }
+    let baseWait = Double(minDelay) * pow(factor, Double(attempt))
+    var jitter = 0
+    if foptBool(options, "jitter", true) && minDelay > 0 {
+      jitter = Int.random(in: 0..<minDelay)
+    }
+    let wait = Int(baseWait) + jitter
+    return wait > maxDelay ? maxDelay : wait
+  }
+
+  private func retryAfter(_ res: Value) -> (Int, Bool) {
+    let (v, has) = fresHeader(res, "retry-after")
+    if !has {
+      return (0, false)
+    }
+    let seconds = fparseInt(v, -1)
+    if seconds < 0 {
+      return (0, false)
+    }
+    return (seconds * 1000, true)
+  }
+
+  private func sleepMs(_ ms: Int) {
+    if ms <= 0 {
+      return
+    }
+    foptSleep(options)(ms)
+  }
+
+  private func track(_ attempt: Int, _ res: Value, _ err: Error?, _ wait: Int) {
+    attempts += 1
+
+    let entry = VMap()
+    entry.entries["attempt"] = .int(Int64(attempt))
+    entry.entries["wait"] = .int(Int64(wait))
+    let (status, has) = fresStatus(res)
+    if has {
+      entry.entries["status"] = .int(Int64(status))
+    }
+    if let err = err {
+      entry.entries["error"] = .string(errMessage(err))
+    }
+    retries.append(entry)
+  }
+}

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/feature/StreamingFeature.swift

@@ -0,0 +1,82 @@
+// Streaming result support. For list-style operations it attaches a
+// `result.stream` function yielding items so callers can consume them
+// incrementally with `for item in result.stream!()` instead of materialising
+// the whole list at once. A `chunkSize` groups items into `.list` batches
+// when set; a `chunkDelay` (ms) paces delivery via the injectable `sleep`
+// for offline tests.
+
+import Foundation
+
+public final class StreamingFeature: BaseFeature {
+  private var client: ProjectNameSDK?
+  private var options: VMap?
+
+  // Activity tracking (mirrors the ts client._streaming record).
+  public var opened = 0
+
+  public override init() {
+    super.init()
+    version = "0.0.1"
+    name = "streaming"
+    active = true
+  }
+
+  public override func initFeature(_ ctx: Context, _ options: VMap) {
+    client = ctx.client
+    self.options = options
+    active = foptBool(options, "active", false)
+  }
+
+  public override func preResult(_ ctx: Context) {
+    if !active || !streamable(ctx) {
+      return
+    }
+    guard let result = ctx.result else {
+      return
+    }
+
+    result.streaming = true
+    result.stream = { self.iterate(result) }
+
+    opened += 1
+  }
+
+  private func iterate(_ result: Result) -> [Value] {
+    let chunkDelay = foptInt(options, "chunkDelay", 0)
+    let chunkSize = foptInt(options, "chunkSize", 0)
+    let sleep = foptSleep(options)
+
+    // Read lazily at stream() call time so downstream result processing
+    // is reflected.
+    let items = result.resdata.asList?.items ?? []
+
+    var out: [Value] = []
+
+    if chunkSize > 0 {
+      var i = 0
+      while i < items.count {
+        if chunkDelay > 0 {
+          sleep(chunkDelay)
+        }
+        let end = min(i + chunkSize, items.count)
+        out.append(.list(Array(items[i..<end])))
+        i += chunkSize
+      }
+      return out
+    }
+
+    for item in items {
+      if chunkDelay > 0 {
+        sleep(chunkDelay)
+      }
+      out.append(item)
+    }
+    return out
+  }
+
+  private func streamable(_ ctx: Context) -> Bool {
+    let opname = ctx.op?.name ?? ""
+    let ops = foptStrList(options, "ops") ?? ["list"]
+    return ops.contains(opname)
+  }
+}

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/feature/TelemetryFeature.swift

@@ -0,0 +1,119 @@
+// 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). Each span closes exactly
+// once (the per-context marker in ctx.out is consumed on close). Finished
+// spans accumulate on the feature; 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.
+
+import Foundation
+
+public final class TelemetryFeature: BaseFeature {
+  private var client: ProjectNameSDK?
+  private var options: VMap?
+  private var seq = 0
+
+  // Activity tracking (mirrors the ts client._telemetry record).
+  public var spans: [VMap] = []
+  public var activeSpans = 0
+
+  private static let spanKey = "telemetry_span"
+
+  public override init() {
+    super.init()
+    version = "0.0.1"
+    name = "telemetry"
+    active = true
+  }
+
+  public override func initFeature(_ ctx: Context, _ options: VMap) {
+    client = ctx.client
+    self.options = options
+    active = foptBool(options, "active", false)
+    seq = 0
+  }
+
+  public override func prePoint(_ ctx: Context) {
+    if !active {
+      return
+    }
+
+    let entity = ctx.op?.entity ?? "_"
+    let opname = ctx.op?.name ?? "_"
+
+    let span = VMap()
+    span.entries["traceId"] = .string(id("trace"))
+    span.entries["spanId"] = .string(id("span"))
+    span.entries["name"] = .string(entity + "." + opname)
+    span.entries["start"] = .int(foptNow(options)())
+    ctx.out[TelemetryFeature.spanKey] = span
+    activeSpans += 1
+  }
+
+  public override func preRequest(_ ctx: Context) {
+    if !active {
+      return
+    }
+
+    let span = ctx.out[TelemetryFeature.spanKey] as? VMap
+    guard let span = span, let spec = ctx.spec else {
+      return
+    }
+
+    let h = foptMap(options, "headers")
+    let traceId = gp(span, "traceId").asString ?? ""
+    let spanId = gp(span, "spanId").asString ?? ""
+    spec.headers.entries[foptStr(h, "trace", "X-Trace-Id")] = .string(traceId)
+    spec.headers.entries[foptStr(h, "span", "X-Span-Id")] = .string(spanId)
+    spec.headers.entries[foptStr(h, "parent", "traceparent")] =
+      .string("00-" + traceId + "-" + spanId + "-01")
+  }
+
+  public override func preDone(_ ctx: Context) {
+    close(ctx, ctx.result != nil && ctx.result!.ok && ctx.result!.err == nil)
+  }
+
+  public override func preUnexpected(_ ctx: Context) {
+    close(ctx, false)
+  }
+
+  private func close(_ ctx: Context, _ ok: Bool) {
+    // Close once per operation; a preDone followed by a pipeline failure
+    // (non-2xx) fires preUnexpected too, which then finds no open span.
+    guard let span = ctx.out[TelemetryFeature.spanKey] as? VMap else {
+      return
+    }
+    ctx.out.removeValue(forKey: TelemetryFeature.spanKey)
+
+    let end = foptNow(options)()
+    let start = toLong(gp(span, "start"))
+    var dur = end - start
+    if dur < 0 {
+      dur = 0
+    }
+    span.entries["end"] = .int(end)
+    span.entries["durationMs"] = .int(dur)
+    span.entries["ok"] = .bool(ok)
+
+    activeSpans -= 1
+    spans.append(span)
+
+    if let exporter = gp(options, "exporter").asNative as? (VMap) -> Void {
+      exporter(span)
+    }
+  }
+
+  private func id(_ kind: String) -> String {
+    if let idgen = gp(options, "idgen").asNative as? (String) -> String {
+      return idgen(kind)
+    }
+    // Deterministic-ish sequential id; unique within a client instance.
+    seq += 1
+    var n = String(seq, radix: 16)
+    while n.count < 4 { n = "0" + n }
+    let prefix = kind == "trace" ? "t" : "s"
+    while n.count < 16 { n += "0" }
+    return prefix + n
+  }
+}

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/feature/TestFeature.swift

@@ -0,0 +1,257 @@
+// In-memory mock transport for testing without a live server. Serves the
+// per-entity fixture data supplied via the test feature options (`entity`) and
+// answers CRUD requests the way a REST server would. An optional `net` block
+// layers deterministic network-behaviour simulation over the mock.
+
+import Foundation
+
+private func testRespond(_ status: Int, _ data: Value, _ extra: VMap?) -> Value {
+  let res = VMap()
+  res.entries["status"] = .int(Int64(status))
+  res.entries["statusText"] = .string("OK")
+  let captured = data
+  res.entries["json"] = .nat({ () -> Value in captured } as NativeCall0)
+  res.entries["body"] = .string("not-used")
+  if let extra = extra {
+    for (k, v) in extra.entries { res.entries[k] = v }
+  }
+  return .map(res)
+}
+
+// For single-entity ops with an empty explicit match, fall back to the id the
+// entity client already knows from a prior create/load.
+private func testResolveMatch(_ ctx2: Context, _ explicitMatch: VMap) -> VMap {
+  if explicitMatch.entries.count > 0 { return explicitMatch }
+  for src in [ctx2.match, ctx2.data] {
+    let v = gp(src, "id")
+    if !isNil(v) && v != .string("__UNDEFINED__") {
+      let m = VMap()
+      m.entries["id"] = v
+      return m
+    }
+  }
+  return VMap()
+}
+
+private func testBuildArgs(_ ctx: Context, _ op: Operation, _ args: VMap?) -> Value {
+  let opname = op.name
+
+  let cfg: Value = ctx.config == nil ? .noval : .map(ctx.config!)
+  let points = getpath(cfg, jtp("entity", ctx.entity!.getName(), "op", opname, "points"))
+  let point = getelem(points, .int(-1))
+
+  let paramsPath = getpath(point, jtp("args", "params"))
+  let reqdParams = select(paramsPath, .map(vm(("reqd", .bool(true)))))
+  let reqd = transform(reqdParams, jtp("`$EACH`", "", "`$KEY.name`"))
+
+  let qand = VList()
+  let q = VMap()
+  q.entries["`$AND`"] = .list(qand)
+
+  if let args = args {
+    for key in keysof(.map(args)) {
+      let isId = key == "id"
+      let selected = select(reqd, .string(key))
+      let isReqd = !isempty(selected)
+
+      if isId || isReqd {
+        let v = ctx.utility!.param(ctx, .string(key))
+        let ka = gp(op.alias, key)
+
+        let qor = VList()
+        let qm1 = VMap()
+        qm1.entries[key] = v
+        qor.items.append(.map(qm1))
+        if let kas = ka.asString {
+          let qm2 = VMap()
+          qm2.entries[kas] = v
+          qor.items.append(.map(qm2))
+        }
+
+        let qorm = VMap()
+        qorm.entries["`$OR`"] = .list(qor)
+        qand.items.append(.map(qorm))
+      }
+    }
+  }
+
+  if let explain = ctx.ctrl.explain {
+    let tm = VMap()
+    tm.entries["query"] = .map(q)
+    explain.entries["test"] = .map(tm)
+  }
+
+  return .map(q)
+}
+
+public final class TestFeature: BaseFeature {
+  private var client: ProjectNameSDK?
+  private var options: VMap?
+  private var netcalls = 0
+
+  public override init() {
+    super.init()
+    version = "0.0.1"
+    name = "test"
+    active = true
+  }
+
+  public override func initFeature(_ ctx: Context, _ options: VMap) {
+    client = ctx.client
+    self.options = options
+
+    let entity = gp(options, "entity").asMap ?? VMap()
+
+    client!.mode = "test"
+
+    // Ensure entity ids are correct.
+    _ = walk(.map(entity), { key, val, _, path in
+      if path.count == 2, val.isMap, key.asString != nil {
+        val.asMap!.entries["id"] = .string(strkey(key))
+      }
+      return val
+    }, nil)
+
+    let testFetcher: FetcherFunc = { ctx2, _fullurl, _fetchdef in
+      let op = ctx2.op!
+      let entmap = gp(entity, op.entity).asMap ?? VMap()
+
+      if op.name == "load" {
+        let args = testBuildArgs(ctx2, op, testResolveMatch(ctx2, ctx2.reqmatch))
+        let found = select(.map(entmap), args)
+        let ent = getelem(found, .int(0))
+        if isNil(ent) {
+          let extra = VMap()
+          extra.entries["statusText"] = .string("Not found")
+          return testRespond(404, .noval, extra)
+        }
+        delprop(ent, .string("$KEY"))
+        return testRespond(200, clone(ent), nil)
+      } else if op.name == "list" {
+        let args = testBuildArgs(ctx2, op, ctx2.reqmatch)
+        let found = select(.map(entmap), args)
+        if isNil(found) {
+          let extra = VMap()
+          extra.entries["statusText"] = .string("Not found")
+          return testRespond(404, .noval, extra)
+        }
+        if let fl = found.asList {
+          for item in fl.items { delprop(item, .string("$KEY")) }
+        }
+        return testRespond(200, clone(found), nil)
+      } else if op.name == "update" {
+        var updateMatch = VMap()
+        if let idv = ctx2.reqdata.entries["id"] {
+          updateMatch.entries["id"] = idv
+        }
+        if let alias = op.alias, let aliasId = gp(alias, "id").asString,
+          let av = ctx2.reqdata.entries[aliasId] {
+          updateMatch.entries[aliasId] = av
+        }
+        if updateMatch.entries.count == 0 {
+          updateMatch = testResolveMatch(ctx2, VMap())
+        }
+        let args = testBuildArgs(ctx2, op, updateMatch)
+        let found = select(.map(entmap), args)
+        var ent = getelem(found, .int(0))
+        if isNil(ent) {
+          for (_, e) in entmap.entries where e.isMap { ent = e; break }
+        }
+        if isNil(ent) {
+          let extra = VMap()
+          extra.entries["statusText"] = .string("Not found")
+          return testRespond(404, .noval, extra)
+        }
+        if let entm = ent.asMap {
+          for (k, v) in ctx2.reqdata.entries { entm.entries[k] = v }
+        }
+        delprop(ent, .string("$KEY"))
+        return testRespond(200, clone(ent), nil)
+      } else if op.name == "remove" {
+        let args = testBuildArgs(ctx2, op, testResolveMatch(ctx2, ctx2.reqmatch))
+        let found = select(.map(entmap), args)
+        let ent = getelem(found, .int(0))
+        if let entm2 = ent.asMap {
+          let id = gp(entm2, "id")
+          delprop(.map(entmap), id)
+        }
+        return testRespond(200, .noval, nil)
+      } else if op.name == "create" {
+        _ = testBuildArgs(ctx2, op, ctx2.reqdata)
+        var id = ctx2.utility!.param(ctx2, .string("id"))
+        if isNil(id) {
+          id = .string(String(
+            format: "%04x%04x%04x%04x",
+            Int.random(in: 0..<0x10000), Int.random(in: 0..<0x10000),
+            Int.random(in: 0..<0x10000), Int.random(in: 0..<0x10000)))
+        }
+        let ent = clone(.map(ctx2.reqdata))
+        if let entm = ent.asMap {
+          entm.entries["id"] = id
+          if let idStr = id.asString { entmap.entries[idStr] = .map(entm) }
+          delprop(.map(entm), .string("$KEY"))
+          return testRespond(200, clone(.map(entm)), nil)
+        }
+        return testRespond(200, ent, nil)
+      }
+
+      let extra = VMap()
+      extra.entries["statusText"] = .string("Unknown operation")
+      return testRespond(404, .noval, extra)
+    }
+
+    // Optional network behaviour simulation over the mock transport.
+    let net = gp(options, "net").asMap
+    ctx.utility!.fetcher = net == nil ? testFetcher : makeNetsim(net!, testFetcher)
+  }
+
+  private func makeNetsim(_ net: VMap, _ inner: @escaping FetcherFunc) -> FetcherFunc {
+    netcalls = 0
+
+    func pickLatency() -> Int {
+      let l = gp(net, "latency")
+      if isNil(l) { return 0 }
+      if let lm = l.asMap {
+        let mn = foptInt(lm, "min", 0)
+        let mx = foptInt(lm, "max", mn)
+        if mx <= mn { return mn }
+        return mn + ((mx - mn) >> 1)
+      }
+      let fixedMs = foptInt(net, "latency", 0)
+      return fixedMs < 0 ? 0 : fixedMs
+    }
+
+    func sleepMs(_ ms: Int) {
+      if ms <= 0 { return }
+      foptSleep(net)(ms)
+    }
+
+    return { [weak self] ctx, url, fetchdef in
+      guard let self = self else { return try inner(ctx, url, fetchdef) }
+      self.netcalls += 1
+      let call = self.netcalls
+
+      if foptBool(net, "offline", false) {
+        sleepMs(pickLatency())
+        throw ctx.makeError("netsim_offline", "Simulated network offline (URL was: \"\(url)\")")
+      }
+      if call <= foptInt(net, "errorTimes", 0) {
+        sleepMs(pickLatency())
+        throw ctx.makeError("netsim_conn", "Simulated connection error (call \(call))")
+      }
+      if call <= foptInt(net, "failTimes", 0) {
+        sleepMs(pickLatency())
+        let status = foptInt(net, "failStatus", 503)
+        let r = VMap()
+        r.entries["status"] = .int(Int64(status))
+        r.entries["statusText"] = .string("Simulated Failure")
+        r.entries["body"] = .string("not-used")
+        r.entries["json"] = .nat({ () -> Value in .noval } as NativeCall0)
+        r.entries["headers"] = .map(VMap())
+        return .map(r)
+      }
+      sleepMs(pickLatency())
+      return try inner(ctx, url, fetchdef)
+    }
+  }
+}