@voxgig/sdkgen-langpack 0.0.1

package/.sdk/tm/dart/lib/feature/log/LogFeature.dart

@@ -0,0 +1,85 @@
+// ignore_for_file: non_constant_identifier_names
+
+import '../base/BaseFeature.dart';
+
+// Structured operation logging. Dependency-free: log records are written
+// with print (or a caller-supplied `logger` function receiving the record
+// map), one line per hook, mirroring the donor log feature's record shape.
+class LogFeature extends BaseFeature {
+  dynamic _client;
+  dynamic _logger;
+
+  LogFeature() {
+    version = '0.0.1';
+    name = 'log';
+    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) {
+      var logger = options['logger'];
+
+      if (null == logger) {
+        final level = options['level'] ?? 'info';
+        logger = (dynamic record) {
+          // ignore: avoid_print
+          print('[' +
+              level.toString() +
+              '] ' +
+              (record is Map ? record['hook'].toString() : '') +
+              ' ' +
+              record.toString());
+        };
+      }
+
+      _logger = logger;
+    }
+  }
+
+  @override
+  dynamic PostConstruct(dynamic ctx) => _loghook('PostConstruct', ctx);
+
+  @override
+  dynamic PostConstructEntity(dynamic ctx) =>
+      _loghook('PostConstructEntity', ctx);
+
+  @override
+  dynamic SetData(dynamic ctx) => _loghook('SetData', ctx);
+
+  @override
+  dynamic GetData(dynamic ctx) => _loghook('GetData', ctx);
+
+  @override
+  dynamic GetMatch(dynamic ctx) => _loghook('GetMatch', ctx);
+
+  @override
+  dynamic PrePoint(dynamic ctx) => _loghook('PrePoint', ctx);
+
+  @override
+  dynamic PreSpec(dynamic ctx) => _loghook('PreSpec', ctx);
+
+  @override
+  dynamic PreRequest(dynamic ctx) => _loghook('PreRequest', ctx);
+
+  @override
+  dynamic PreResponse(dynamic ctx) => _loghook('PreResponse', ctx);
+
+  @override
+  dynamic PreResult(dynamic ctx) => _loghook('PreResult', ctx);
+
+  dynamic _loghook(String hook, dynamic ctx) {
+    if (null != _logger) {
+      _logger({
+        'hook': hook,
+        'op': null == ctx.op ? null : ctx.op.name,
+        'client': null == _client ? null : 'ProjectName',
+      });
+    }
+    return null;
+  }
+}

package/.sdk/tm/dart/lib/feature/metrics/MetricsFeature.dart

@@ -0,0 +1,103 @@
+// ignore_for_file: non_constant_identifier_names
+
+import '../base/BaseFeature.dart';
+
+// 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 throws (PreUnexpected). Aggregates live on the client track
+// (`metrics`). The clock is injectable (`now`) for deterministic tests.
+class MetricsFeature extends BaseFeature {
+  dynamic _client;
+  final Map<dynamic, dynamic> _starts = {};
+
+  MetricsFeature() {
+    version = '0.0.1';
+    name = 'metrics';
+    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'];
+    _starts.clear();
+
+    final track = _client.track;
+    if (null == track['metrics']) {
+      track['metrics'] = <String, dynamic>{
+        'total': <String, dynamic>{'count': 0, 'ok': 0, 'err': 0, 'totalMs': 0, 'maxMs': 0},
+        'ops': <String, dynamic>{},
+      };
+    }
+    return null;
+  }
+
+  @override
+  dynamic PrePoint(dynamic ctx) {
+    _starts[ctx] = _now();
+    return null;
+  }
+
+  @override
+  dynamic PreDone(dynamic ctx) {
+    // Classify by the actual result: a 4xx/5xx that flows through still
+    // reaches PreDone before the pipeline throws.
+    _record(
+        ctx,
+        null != ctx.result &&
+            false != ctx.result.ok &&
+            null == ctx.result.err);
+    return null;
+  }
+
+  @override
+  dynamic PreUnexpected(dynamic ctx) {
+    _record(ctx, false);
+    return null;
+  }
+
+  void _record(dynamic ctx, bool ok) {
+    // Record once per operation. When a non-2xx result reaches PreDone the
+    // pipeline then throws, firing PreUnexpected too; the missing start
+    // marker makes the second call a no-op.
+    if (!_starts.containsKey(ctx)) {
+      return;
+    }
+    final start = _starts[ctx];
+    var dur = null == start ? 0 : _now() - start;
+    dur = dur < 0 ? 0 : dur;
+    _starts.remove(ctx);
+
+    final m = _client.track['metrics'];
+    final key = (null == ctx.op ? '_' : (ctx.op.entity ?? '_')).toString() +
+        '.' +
+        (null == ctx.op ? '_' : (ctx.op.name ?? '_')).toString();
+
+    var op = m['ops'][key];
+    if (null == op) {
+      op = m['ops'][key] = <String, dynamic>{'count': 0, 'ok': 0, 'err': 0, 'totalMs': 0, 'maxMs': 0};
+    }
+
+    _bump(m['total'], ok, dur);
+    _bump(op, ok, dur);
+  }
+
+  void _bump(dynamic bucket, bool ok, num dur) {
+    bucket['count']++;
+    bucket[ok ? 'ok' : 'err']++;
+    bucket['totalMs'] += dur;
+    if (dur > bucket['maxMs']) {
+      bucket['maxMs'] = dur;
+    }
+  }
+
+  num _now() {
+    final now = options['now'];
+    if (now is Function) {
+      return now();
+    }
+    return DateTime.now().millisecondsSinceEpoch;
+  }
+}

package/.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/.sdk/tm/dart/lib/feature/paging/PagingFeature.dart

@@ -0,0 +1,240 @@
+// ignore_for_file: non_constant_identifier_names
+
+import '../../utility/voxgig_struct.dart' as vs;
+
+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) ?? {};
+
+    // GraphQL paginates through operation VARIABLES, not the query string.
+    // This hook runs after makeSpec, so spec.body already holds the
+    // { query, variables } envelope, and before makeFetchDef serialises it.
+    if ('graphql' == ctx.point?.kind) {
+      _graphqlPreRequest(ctx, paging);
+      return 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;
+  }
+
+  // Relay pagination: the cursor is the `after` variable (or whatever the
+  // model named it), and the page size is `first`.
+  void _graphqlPreRequest(dynamic ctx, dynamic paging) {
+    final body = ctx.spec.body;
+    if (body is! Map) {
+      return;
+    }
+
+    var variables = body['variables'];
+    if (variables is! Map) {
+      variables = <String, dynamic>{};
+      body['variables'] = variables;
+    }
+
+    final afterVar = options['afterVar'] ?? 'after';
+    final firstVar = options['firstVar'] ?? 'first';
+
+    // Only bind variables the operation actually declares, or the server
+    // rejects the document.
+    final declared = <String>{};
+    final varlist = vs.getprop(ctx.point?.graphql, 'vars');
+    if (varlist is List) {
+      for (final v in varlist) {
+        final name = vs.getprop(v, 'name');
+        if (null != name) {
+          declared.add(name.toString());
+        }
+      }
+    }
+
+    if (null != paging['cursor'] && declared.contains(afterVar)) {
+      variables[afterVar] = paging['cursor'];
+    }
+
+    if (null != options['limit'] && null == variables[firstVar] &&
+        declared.contains(firstVar)) {
+      variables[firstVar] = options['limit'];
+    }
+  }
+
+  @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);
+      }
+    }
+
+    // Set when the response states hasMore outright, rather than leaving it
+    // to be inferred from the presence of a cursor.
+    var explicitMore = false;
+
+    // Relay connections carry the cursor in pageInfo, at the path the model
+    // recorded for this op.
+    final page = vs.getprop(ctx.point?.graphql, 'page');
+    if (page is Map && body is Map) {
+      // `connpath` locates the connection object inside the response
+      // envelope (data.<field>); the cursor/more paths are relative to it.
+      var conn = body;
+      final connpath = page['connpath'];
+      if (connpath is String && '' != connpath) {
+        final sub = vs.getpath(body, connpath);
+        if (sub is Map) {
+          conn = sub;
+        }
+      }
+
+      final cursorpath = page['cursor'];
+      if (cursorpath is String && '' != cursorpath) {
+        final cursor = vs.getpath(conn, cursorpath);
+        if (null != cursor) {
+          paging['cursor'] = cursor;
+        }
+      }
+
+      final morepath = page['more'];
+      if (morepath is String && '' != morepath) {
+        final more = vs.getpath(conn, morepath);
+        if (more is bool) {
+          paging['hasMore'] = more;
+          explicitMore = true;
+        }
+      }
+    }
+
+    // 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'];
+        explicitMore = true;
+      }
+    }
+
+    // Cursor presence only INFERS another page. When the server stated the
+    // answer outright — relay's `hasNextPage: false`, or a body `hasMore` —
+    // that wins: a final page normally carries both an end cursor and
+    // hasNextPage false, and inferring from the cursor there would send the
+    // caller back for a page that does not exist, forever.
+    if (!explicitMore) {
+      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());
+  }
+}