@voxgig/sdkgen-langpack 0.0.1

package/.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/.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/.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 '';
+    }
+  }
+}

package/.sdk/tm/dart/lib/feature/retry/RetryFeature.dart

@@ -0,0 +1,155 @@
+// ignore_for_file: non_constant_identifier_names
+
+import 'dart:async';
+import 'dart:math';
+
+import '../../utility/ErrUtility.dart';
+import '../../utility/voxgig_struct.dart' as vs;
+
+import '../base/BaseFeature.dart';
+
+// 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 an error, 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.
+class RetryFeature extends BaseFeature {
+  dynamic _client;
+
+  RetryFeature() {
+    version = '0.0.1';
+    name = 'retry';
+    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 self = this;
+    final utility = ctx.utility;
+    final inner = utility.fetcher;
+
+    utility.fetcher = (dynamic ctx2, dynamic url, dynamic fetchdef) async {
+      return self._withRetry(ctx2, url, fetchdef, inner);
+    };
+    return null;
+  }
+
+  Future<dynamic> _withRetry(
+      dynamic ctx, dynamic url, dynamic fetchdef, dynamic inner) async {
+    final opts = options;
+    final max = null == opts['retries'] ? 2 : (opts['retries'] as num).toInt();
+    final minDelay =
+        null == opts['minDelay'] ? 50 : (opts['minDelay'] as num).toInt();
+    final maxDelay =
+        null == opts['maxDelay'] ? 2000 : (opts['maxDelay'] as num).toInt();
+    final factor = null == opts['factor'] ? 2 : opts['factor'];
+
+    var attempt = 0;
+
+    for (;;) {
+      dynamic res;
+      var threw = false;
+      try {
+        res = await Future.value(inner(ctx, url, fetchdef));
+      } catch (err) {
+        threw = true;
+        res = err;
+      }
+
+      final retryable = _retryable(res);
+      if (!retryable || attempt >= max) {
+        // Out of attempts: rethrow a thrown error to preserve pipeline
+        // semantics, otherwise return the last response/error.
+        if (threw && attempt >= max) {
+          throw res;
+        }
+        return res;
+      }
+
+      final wait = _backoff(res, attempt, minDelay, maxDelay, factor);
+      _track(ctx, attempt + 1, res, wait);
+      await _sleep(wait);
+      attempt++;
+    }
+  }
+
+  bool _retryable(dynamic res) {
+    if (null == res) {
+      return true;
+    }
+    if (iserr(res)) {
+      return true;
+    }
+    final status = vs.getprop(res, 'status');
+    if (status is! num) {
+      return false;
+    }
+    final statuses =
+        options['statuses'] ?? [408, 425, 429, 500, 502, 503, 504];
+    return (statuses as List).contains(status);
+  }
+
+  int _backoff(
+      dynamic res, int attempt, int minDelay, int maxDelay, dynamic factor) {
+    // Honour a server-provided Retry-After (seconds) when present.
+    final ra = _retryAfter(res);
+    if (null != ra) {
+      return min(maxDelay, ra);
+    }
+    final base = minDelay * pow(factor is num ? factor : 2, attempt);
+    final jitter = false == options['jitter']
+        ? 0
+        : Random().nextInt(minDelay < 1 ? 1 : minDelay);
+    return min(maxDelay, base.toInt() + jitter);
+  }
+
+  int? _retryAfter(dynamic res) {
+    if (null == res) {
+      return null;
+    }
+    final headers = vs.getprop(res, 'headers');
+    if (headers is! Map) {
+      return null;
+    }
+    final v = headers['retry-after'] ?? headers['Retry-After'];
+    if (null == v) {
+      return null;
+    }
+    final n = v is num ? v : num.tryParse(v.toString());
+    return null == n ? null : (n * 1000).toInt();
+  }
+
+  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 attempt, dynamic res, int wait) {
+    final track = _client.track;
+    if (null == track['retry']) {
+      track['retry'] = <String, dynamic>{'attempts': 0, 'retries': <dynamic>[]};
+    }
+    track['retry']['attempts']++;
+    track['retry']['retries'].add({
+      'attempt': attempt,
+      'status': vs.getprop(res, 'status'),
+      'error': iserr(res) ? errmsg(res) : null,
+      'wait': wait,
+    });
+  }
+}