@voxgig/sdkgen 1.3.8 → 1.3.10

package/project/.sdk/tm/dart/lib/feature/netsim/NetsimFeature.dart

@@ -0,0 +1,186 @@
+// ignore_for_file: non_constant_identifier_names
+
+import 'dart:async';
+
+import '../../utility/voxgig_struct.dart' as vs;
+
+import '../base/BaseFeature.dart';
+
+// Network behaviour simulation. Wraps the active transport (the live
+// dart:io transport 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 NetsimFeature extends BaseFeature {
+  dynamic _client;
+  int _calls = 0;
+  int _seed = 1;
+
+  NetsimFeature() {
+    version = '0.0.1';
+    name = 'netsim';
+    active = true;
+  }
+
+  @override
+  dynamic init(dynamic ctx, dynamic opts) {
+    _client = ctx.client;
+    options = opts is Map ? Map<String, dynamic>.from(opts) : {};
+    active = true == options['active'];
+    _seed = options['seed'] is num ? (options['seed'] as num).toInt() : 1;
+    if (0 == _seed) {
+      _seed = 1;
+    }
+    _calls = 0;
+
+    if (!active) {
+      return null;
+    }
+
+    final self = this;
+    final utility = ctx.utility;
+    final inner = utility.fetcher;
+
+    utility.fetcher = (dynamic ctx2, dynamic url, dynamic fetchdef) async {
+      return self._simulate(ctx2, url, fetchdef, inner);
+    };
+    return null;
+  }
+
+  Future<dynamic> _simulate(
+      dynamic ctx, dynamic url, dynamic fetchdef, dynamic inner) async {
+    final opts = options;
+    _calls++;
+    final call = _calls;
+
+    // Record the simulated conditions for test/debug inspection.
+    final applied = <String, dynamic>{};
+
+    // Total outage: every call fails at the transport level.
+    if (true == opts['offline']) {
+      await _sleep(_pickLatency());
+      applied['offline'] = true;
+      _track(ctx, applied);
+      return ctx.error('netsim_offline',
+          'Simulated network offline (URL was: "' + url.toString() + '")');
+    }
+
+    // Connection-level errors for the first N calls (e.g. ECONNRESET).
+    final errorTimes =
+        opts['errorTimes'] is num ? (opts['errorTimes'] as num).toInt() : 0;
+    if (call <= errorTimes) {
+      await _sleep(_pickLatency());
+      applied['error'] = true;
+      _track(ctx, applied);
+      return ctx.error('netsim_conn',
+          'Simulated connection error (call ' + call.toString() + ')');
+    }
+
+    // Rate-limit responses (HTTP 429 + Retry-After) for the first N calls.
+    final rateLimitTimes = opts['rateLimitTimes'] is num
+        ? (opts['rateLimitTimes'] as num).toInt()
+        : 0;
+    if (call <= rateLimitTimes) {
+      await _sleep(_pickLatency());
+      applied['rateLimited'] = true;
+      _track(ctx, applied);
+      return _respond(ctx, 429, null, {
+        'statusText': 'Too Many Requests',
+        'headers': {
+          'retry-after':
+              (null == opts['retryAfter'] ? 0 : opts['retryAfter']).toString()
+        },
+      });
+    }
+
+    // Retryable failure status for the first N calls, or every Nth call.
+    final failStatus = null == opts['failStatus'] ? 503 : opts['failStatus'];
+    final failTimes =
+        opts['failTimes'] is num ? (opts['failTimes'] as num).toInt() : 0;
+    final failEvery =
+        opts['failEvery'] is num ? (opts['failEvery'] as num).toInt() : 0;
+    final failRate = opts['failRate'] is num ? opts['failRate'] as num : 0;
+    final failByCount = call <= failTimes;
+    final failByEvery = 0 < failEvery && 0 == call % failEvery;
+    final failByRate = 0 < failRate && _rand() < failRate;
+    if (failByCount || failByEvery || failByRate) {
+      await _sleep(_pickLatency());
+      applied['failStatus'] = failStatus;
+      _track(ctx, applied);
+      return _respond(ctx, failStatus, null, {'statusText': 'Simulated Failure'});
+    }
+
+    // Otherwise: apply latency then delegate to the real transport.
+    final latency = _pickLatency();
+    applied['latency'] = latency;
+    _track(ctx, applied);
+    await _sleep(latency);
+    return inner(ctx, url, fetchdef);
+  }
+
+  // Latency in ms: a fixed number, or a uniform sample from {min,max}.
+  int _pickLatency() {
+    final l = options['latency'];
+    if (null == l) {
+      return 0;
+    }
+    if (l is num) {
+      return l < 0 ? 0 : l.toInt();
+    }
+    final min = l['min'] is num ? (l['min'] as num).toInt() : 0;
+    final max = null == l['max'] ? min : (l['max'] as num).toInt();
+    if (max <= min) {
+      return min;
+    }
+    return min + (_rand() * (max - min)).floor();
+  }
+
+  Future<void> _sleep(int ms) {
+    if (0 >= ms) {
+      return Future.value();
+    }
+    final sleeper = options['sleep'];
+    if (sleeper is Function) {
+      return Future.value(sleeper(ms)).then((_x) {});
+    }
+    return Future.delayed(Duration(milliseconds: ms));
+  }
+
+  // Deterministic 0..1 pseudo-random via a linear congruential generator.
+  double _rand() {
+    _seed = (_seed * 1103515245 + 12345) & 0x7fffffff;
+    return _seed / 0x7fffffff;
+  }
+
+  void _track(dynamic ctx, dynamic applied) {
+    final track = _client.track;
+    if (null == track['netsim']) {
+      track['netsim'] = <String, dynamic>{'calls': 0, 'applied': <dynamic>[]};
+    }
+    track['netsim']['calls']++;
+    track['netsim']['applied'].add(applied);
+    if (ctx.ctrl is Map && null != ctx.ctrl['explain']) {
+      ctx.ctrl['explain']['netsim'] = track['netsim'];
+    }
+  }
+
+  // Build a transport-shaped response (matching the test feature's mock).
+  dynamic _respond(dynamic ctx, dynamic status, [dynamic data, dynamic extra]) {
+    final out = vs.merge([
+      <String, dynamic>{
+        'status': status,
+        'statusText': 'OK',
+        'json': () => data,
+        'body': 'not-used',
+      },
+      vs.getdef(extra, {}),
+    ]);
+
+    out['headers'] = vs.getprop(out, 'headers', {});
+
+    return out;
+  }
+}

package/project/.sdk/tm/dart/lib/feature/paging/PagingFeature.dart

@@ -0,0 +1,145 @@
+// ignore_for_file: non_constant_identifier_names
+
+import '../base/BaseFeature.dart';
+
+// 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-Next-Page`/`X-Total-Count` headers, or `next`/
+// `cursor`/`hasMore` fields in the body — and records them on
+// `ctx.result.paging`. Generated SDKs build auto-iteration on top of this
+// (advance the cursor/page and re-issue the list call until `hasMore` is
+// false). Parameter names and page size are configurable.
+class PagingFeature extends BaseFeature {
+  dynamic _client;
+
+  PagingFeature() {
+    version = '0.0.1';
+    name = 'paging';
+    active = true;
+  }
+
+  @override
+  dynamic init(dynamic ctx, dynamic opts) {
+    _client = ctx.client;
+    options = opts is Map ? Map<String, dynamic>.from(opts) : {};
+    active = true == options['active'];
+    return null;
+  }
+
+  @override
+  dynamic PreRequest(dynamic ctx) {
+    if (!_isList(ctx)) {
+      return null;
+    }
+    final spec = ctx.spec;
+    if (null == spec) {
+      return null;
+    }
+    spec.query ??= {};
+
+    final pageParam = options['pageParam'] ?? 'page';
+    final limitParam = options['limitParam'] ?? 'limit';
+    final cursorParam = options['cursorParam'] ?? 'cursor';
+
+    // A per-call cursor/page from ctrl takes priority (used by auto-iteration).
+    final paging = (ctx.ctrl is Map ? ctx.ctrl['paging'] : null) ?? {};
+
+    if (null != paging['cursor']) {
+      spec.query[cursorParam] = paging['cursor'];
+    } else if (null == spec.query[pageParam]) {
+      spec.query[pageParam] =
+          null != paging['page'] ? paging['page'] : (options['startPage'] ?? 1);
+    }
+
+    if (null != options['limit'] && null == spec.query[limitParam]) {
+      spec.query[limitParam] = options['limit'];
+    }
+    return null;
+  }
+
+  @override
+  dynamic PreResult(dynamic ctx) {
+    if (!_isList(ctx)) {
+      return null;
+    }
+    final result = ctx.result;
+    if (null == result) {
+      return null;
+    }
+
+    final headers = result.headers ?? {};
+    final body = result.body;
+
+    final paging = <String, dynamic>{
+      'page': _num(_header(headers, 'x-page')),
+      'totalCount': _num(_header(headers, 'x-total-count')),
+      'nextPage': _num(_header(headers, 'x-next-page')),
+      'next': null,
+      'cursor': null,
+      'hasMore': false,
+    };
+
+    // Link: <...>; rel="next"
+    final link = _header(headers, 'link');
+    if (null != link) {
+      final m = RegExp(r'<([^>]+)>\s*;\s*rel="?next"?', caseSensitive: false)
+          .firstMatch(link.toString());
+      if (null != m) {
+        paging['next'] = m.group(1);
+      }
+    }
+
+    // Body-level cursors.
+    if (body is Map) {
+      if (null != body['next']) {
+        paging['next'] = paging['next'] ?? body['next'];
+      }
+      if (null != body['cursor']) {
+        paging['cursor'] = body['cursor'];
+      }
+      if (null != body['nextCursor']) {
+        paging['cursor'] = body['nextCursor'];
+      }
+      if (body['hasMore'] is bool) {
+        paging['hasMore'] = body['hasMore'];
+      }
+    }
+
+    paging['hasMore'] = true == paging['hasMore'] ||
+        null != paging['next'] ||
+        null != paging['cursor'] ||
+        null != paging['nextPage'];
+
+    result.paging = paging;
+
+    final track = _client.track;
+    track['paging'] = <String, dynamic>{'last': paging};
+    return null;
+  }
+
+  bool _isList(dynamic ctx) {
+    final ops = options['ops'] ?? ['list'];
+    return (ops as List).contains(null == ctx.op ? null : ctx.op.name);
+  }
+
+  dynamic _header(dynamic headers, String name) {
+    final lower = name.toLowerCase();
+    if (headers is! Map) {
+      return null;
+    }
+    for (final k in headers.keys) {
+      if (k.toString().toLowerCase() == lower) {
+        return headers[k];
+      }
+    }
+    return null;
+  }
+
+  num? _num(dynamic v) {
+    if (null == v) {
+      return null;
+    }
+    return v is num ? v : num.tryParse(v.toString());
+  }
+}

package/project/.sdk/tm/dart/lib/feature/proxy/ProxyFeature.dart

@@ -0,0 +1,118 @@
+// ignore_for_file: non_constant_identifier_names
+
+import 'dart:io';
+
+import '../base/BaseFeature.dart';
+
+// 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. Constructing a
+// concrete proxied client is transport-specific, so a factory may be
+// supplied via `options.agent`; when absent the request is annotated with
+// `fetchdef.proxy` for the transport to honour. Hosts matching `noProxy`
+// bypass the proxy.
+class ProxyFeature extends BaseFeature {
+  dynamic _client;
+  dynamic _url;
+  List<String> _noProxy = [];
+
+  ProxyFeature() {
+    version = '0.0.1';
+    name = 'proxy';
+    active = true;
+  }
+
+  @override
+  dynamic init(dynamic ctx, dynamic opts) {
+    _client = ctx.client;
+    options = opts is Map ? Map<String, dynamic>.from(opts) : {};
+    active = true == options['active'];
+
+    if (!active) {
+      return null;
+    }
+
+    _url = options['url'];
+    dynamic noProxy = options['noProxy'];
+
+    if (true == options['fromEnv']) {
+      final env = Platform.environment;
+      _url = _url ??
+          env['HTTPS_PROXY'] ??
+          env['https_proxy'] ??
+          env['HTTP_PROXY'] ??
+          env['http_proxy'];
+      noProxy = noProxy ?? env['NO_PROXY'] ?? env['no_proxy'];
+    }
+
+    _noProxy = (noProxy is String
+            ? noProxy.split(RegExp(r'\s*,\s*'))
+            : (noProxy is List ? noProxy.map((s) => s.toString()).toList() : <String>[]))
+        .where((s) => '' != s)
+        .map((s) => s.toString())
+        .toList();
+
+    final self = this;
+    final utility = ctx.utility;
+    final inner = utility.fetcher;
+
+    utility.fetcher = (dynamic ctx2, dynamic url, dynamic fetchdef) async {
+      fetchdef = self._route(url, fetchdef);
+      return inner(ctx2, url, fetchdef);
+    };
+    return null;
+  }
+
+  dynamic _route(dynamic url, dynamic fetchdef) {
+    if (null == _url || _bypass(url.toString())) {
+      return fetchdef;
+    }
+
+    final out = <String, dynamic>{};
+    if (fetchdef is Map) {
+      fetchdef.forEach((k, v) => out[k.toString()] = v);
+    }
+    out['proxy'] = _url;
+
+    final agent = options['agent'];
+    if (agent is Function) {
+      // Factory returns a transport-specific agent/dispatcher.
+      final made = agent(_url, url);
+      out['dispatcher'] = made;
+      out['agent'] = made;
+    }
+
+    _track(url);
+    return out;
+  }
+
+  bool _bypass(String url) {
+    if (0 == _noProxy.length) {
+      return false;
+    }
+    var host = url;
+    final m = RegExp(r'^[a-z]+://([^/:]+)', caseSensitive: false).firstMatch(url);
+    if (null != m) {
+      host = m.group(1)!;
+    }
+    for (final np in _noProxy) {
+      if ('*' == np) {
+        return true;
+      }
+      if (host == np ||
+          host.endsWith('.' + np.replaceFirst(RegExp(r'^\.'), ''))) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  void _track(dynamic url) {
+    final track = _client.track;
+    if (null == track['proxy']) {
+      track['proxy'] = {'routed': 0, 'url': _url};
+    }
+    track['proxy']['routed']++;
+  }
+}

package/project/.sdk/tm/dart/lib/feature/ratelimit/RatelimitFeature.dart

@@ -0,0 +1,103 @@
+// ignore_for_file: non_constant_identifier_names
+
+import 'dart:async';
+
+import '../base/BaseFeature.dart';
+
+// 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`). 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 RatelimitFeature extends BaseFeature {
+  dynamic _client;
+  num _tokens = 0;
+  num _last = 0;
+
+  RatelimitFeature() {
+    version = '0.0.1';
+    name = 'ratelimit';
+    active = true;
+  }
+
+  @override
+  dynamic init(dynamic ctx, dynamic opts) {
+    _client = ctx.client;
+    options = opts is Map ? Map<String, dynamic>.from(opts) : {};
+    active = true == options['active'];
+
+    if (!active) {
+      return null;
+    }
+
+    final burst = null == options['burst']
+        ? (options['rate'] ?? 5)
+        : options['burst'];
+    _tokens = burst is num ? burst : 5;
+    _last = _now();
+
+    final self = this;
+    final utility = ctx.utility;
+    final inner = utility.fetcher;
+
+    utility.fetcher = (dynamic ctx2, dynamic url, dynamic fetchdef) async {
+      await self._acquire(ctx2);
+      return inner(ctx2, url, fetchdef);
+    };
+    return null;
+  }
+
+  Future<void> _acquire(dynamic ctx) async {
+    final rate = (options['rate'] ?? 5) as num;
+    final burst = (null == options['burst'] ? rate : options['burst']) as num;
+
+    // Refill according to elapsed time.
+    final now = _now();
+    final elapsed = now - _last;
+    _last = now;
+    final refilled = _tokens + (elapsed / 1000) * rate;
+    _tokens = refilled < burst ? refilled : burst;
+
+    if (_tokens >= 1) {
+      _tokens -= 1;
+      return;
+    }
+
+    // Not enough tokens: wait for one to accrue, then consume it.
+    final needed = 1 - _tokens;
+    final waitMs = ((needed / rate) * 1000).ceil();
+    _track(ctx, waitMs);
+    await _sleep(waitMs);
+    _last = _now();
+    _tokens = 0;
+  }
+
+  num _now() {
+    final now = options['now'];
+    if (now is Function) {
+      return now();
+    }
+    return DateTime.now().millisecondsSinceEpoch;
+  }
+
+  Future<void> _sleep(int ms) {
+    if (0 >= ms) {
+      return Future.value();
+    }
+    final sleeper = options['sleep'];
+    if (sleeper is Function) {
+      return Future.value(sleeper(ms)).then((_x) {});
+    }
+    return Future.delayed(Duration(milliseconds: ms));
+  }
+
+  void _track(dynamic ctx, int waitMs) {
+    final track = _client.track;
+    if (null == track['ratelimit']) {
+      track['ratelimit'] = <String, dynamic>{'throttled': 0, 'waitMs': 0};
+    }
+    track['ratelimit']['throttled']++;
+    track['ratelimit']['waitMs'] += waitMs;
+  }
+}

package/project/.sdk/tm/dart/lib/feature/rbac/RbacFeature.dart

@@ -0,0 +1,121 @@
+// ignore_for_file: non_constant_identifier_names
+
+import '../../utility/voxgig_struct.dart' as vs;
+
+import '../base/BaseFeature.dart';
+
+// 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 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).
+class RbacFeature extends BaseFeature {
+  dynamic _client;
+  final Map<String, bool> _granted = {};
+
+  RbacFeature() {
+    version = '0.0.1';
+    name = 'rbac';
+    active = true;
+  }
+
+  @override
+  dynamic init(dynamic ctx, dynamic opts) {
+    _client = ctx.client;
+    options = opts is Map ? Map<String, dynamic>.from(opts) : {};
+    active = true == options['active'];
+
+    _granted.clear();
+    final perms = options['permissions'] ?? [];
+    for (final p in perms) {
+      _granted[p.toString()] = true;
+    }
+    return null;
+  }
+
+  @override
+  dynamic PrePoint(dynamic ctx) {
+    if (!active) {
+      return null;
+    }
+
+    final required = _required(ctx);
+    if (null == required) {
+      // No rule: honour the default policy.
+      if (true == options['deny']) {
+        return _reject(ctx, '<default-deny>');
+      }
+      return null;
+    }
+
+    if (true == _granted['*'] || true == _granted[required]) {
+      _track(ctx, required, true);
+      return null;
+    }
+
+    return _reject(ctx, required);
+  }
+
+  String? _required(dynamic ctx) {
+    final rules = options['rules'] ?? {};
+    final entity = _entname(ctx.entity) != ''
+        ? _entname(ctx.entity)
+        : (null == ctx.op ? '' : (ctx.op.entity ?? '')).toString();
+    final opname = (null == ctx.op ? '' : (ctx.op.name ?? '')).toString();
+
+    if (null != vs.getprop(rules, entity + '.' + opname)) {
+      return vs.getprop(rules, entity + '.' + opname).toString();
+    }
+    if (null != vs.getprop(rules, opname)) {
+      return vs.getprop(rules, opname).toString();
+    }
+    if (null != vs.getprop(rules, '*')) {
+      return vs.getprop(rules, '*').toString();
+    }
+    return null;
+  }
+
+  dynamic _reject(dynamic ctx, String required) {
+    _track(ctx, required, false);
+    final err = ctx.error(
+        'rbac_denied',
+        'Permission "' +
+            required +
+            '" required for operation "' +
+            (null == ctx.op ? '?' : (ctx.op.name ?? '?')).toString() +
+            '"');
+    // Short-circuit endpoint resolution; the pipeline surfaces this error.
+    ctx.out['point'] = err;
+    return err;
+  }
+
+  void _track(dynamic ctx, String required, bool allowed) {
+    final track = _client.track;
+    if (null == track['rbac']) {
+      track['rbac'] = <String, dynamic>{'allowed': 0, 'denied': 0, 'last': null};
+    }
+    track['rbac'][allowed ? 'allowed' : 'denied']++;
+    track['rbac']['last'] = <String, dynamic>{
+      'required': required,
+      'allowed': allowed,
+      'op': null == ctx.op ? null : ctx.op.name,
+    };
+  }
+
+  String _entname(dynamic ent) {
+    if (null == ent) {
+      return '';
+    }
+    if (ent is Map) {
+      return (vs.getprop(ent, 'name', '') ?? '').toString();
+    }
+    try {
+      return (ent.name ?? '').toString();
+    } catch (_e) {
+      return '';
+    }
+  }
+}