@voxgig/sdkgen-langpack 0.0.1

package/.sdk/tm/dart/lib/feature/test/TestFeature.dart

@@ -0,0 +1,328 @@
+// ignore_for_file: non_constant_identifier_names
+
+import 'dart:async';
+import 'dart:math';
+
+import '../../utility/voxgig_struct.dart' as vs;
+
+import '../base/BaseFeature.dart';
+
+const S_NOT_FOUND = 'Not found';
+
+class TestFeature extends BaseFeature {
+  dynamic _client;
+  int _netcalls = 0;
+
+  TestFeature() {
+    version = '0.0.1';
+    name = 'test';
+    active = true;
+  }
+
+  @override
+  dynamic init(dynamic ctx, dynamic opts) {
+    _client = ctx.client;
+    options = opts is Map ? Map<String, dynamic>.from(opts) : {};
+
+    final entity = options['entity'];
+
+    _client.mode = 'test';
+
+    // Ensure entity ids are correct.
+    vs.walk(entity, before: (k, v, parent, path) {
+      if (2 == vs.size(path)) {
+        vs.setprop(v, 'id', k);
+      }
+      return v;
+    });
+
+    final self = this;
+
+    // THE MOCK HAS TO AGREE WITH THE MODEL. A point carrying
+    // `transform.res: `body.item`` describes an API that answers
+    // {"item": {...}}, and the response transform unwraps that key on the way
+    // back. Returning the bare payload means the transform unwraps a property
+    // that is not there and the caller gets nothing. Mirrors the go/ts/lua/php
+    // mocks.
+    dynamic envelope(dynamic fctx, dynamic data) {
+      if (null == data || null == fctx || null == fctx.point) {
+        return data;
+      }
+      // dart wraps the point in a Point OBJECT (Context._aspoint), so its
+      // fields are typed properties, not map keys — vs.getprop on it returns
+      // null and the envelope silently never applies.
+      final tm = fctx.point.transform;
+      final spec = vs.getprop(tm, 'res');
+      if (spec is! String) {
+        return data;
+      }
+      // Exactly `body.<key>`; a deeper path is not an envelope this mock can
+      // synthesise, so it is left alone rather than guessed at.
+      final m = RegExp(r'^`body\.([^`.]+)`$').firstMatch(spec);
+      if (null == m) {
+        return data;
+      }
+      return <String, dynamic>{m.group(1)!: data};
+    }
+
+    dynamic respond(dynamic fctx, int status, [dynamic data, dynamic res]) {
+      final payload = envelope(fctx, data);
+      final out = vs.merge([
+        <String, dynamic>{
+          'status': status,
+          'statusText': 'OK',
+          'json': () => payload,
+          'body': 'not-used',
+        },
+        vs.getdef(res, {}),
+      ]);
+
+      final headers = vs.getprop(out, 'headers', {});
+      out['headers'] = headers;
+
+      return out;
+    }
+
+    dynamic testFetcher(dynamic fctx, dynamic _fullurl, dynamic _fetchdef) {
+      final param = fctx.utility.param;
+
+      final op = fctx.op;
+      final entmap = vs.getprop(entity, op.entity, {});
+
+      if ('load' == op.name) {
+        final args = self.buildArgs(fctx, op, fctx.reqmatch);
+        final found = vs.select(entmap, args);
+        final ent = vs.getelem(found, 0);
+        if (null == ent) {
+          return respond(fctx, 404, null, {'statusText': S_NOT_FOUND});
+        } else {
+          vs.delprop(ent, r'$KEY');
+          final out = vs.clone(ent);
+          return respond(fctx, 200, out);
+        }
+      } else if ('list' == op.name) {
+        final args = self.buildArgs(fctx, op, fctx.reqmatch);
+        final found = vs.select(entmap, args);
+        if (null == found) {
+          return respond(fctx, 404, null, {'statusText': S_NOT_FOUND});
+        } else {
+          for (final ent in found) {
+            vs.delprop(ent, r'$KEY');
+          }
+          final out = vs.clone(found);
+          return respond(fctx, 200, out);
+        }
+      } else if ('update' == op.name) {
+        final args = self.buildArgs(fctx, op, fctx.reqdata);
+        final found = vs.select(entmap, args);
+        final ent = vs.getelem(found, 0);
+        if (null == ent) {
+          return respond(fctx, 404, null, {'statusText': S_NOT_FOUND});
+        } else {
+          // Dart's single null stands in for the donor's undefined: merge
+          // must not overwrite stored values with absent ones.
+          final upddata = <String, dynamic>{};
+          if (fctx.reqdata is Map) {
+            (fctx.reqdata as Map).forEach((k, v) {
+              if (null != v) {
+                upddata[k.toString()] = v;
+              }
+            });
+          }
+          vs.merge([ent, upddata]);
+          vs.delprop(ent, r'$KEY');
+          final out = vs.clone(ent);
+          return respond(fctx, 200, out);
+        }
+      } else if ('remove' == op.name) {
+        final args = self.buildArgs(fctx, op, fctx.reqmatch);
+        final found = vs.select(entmap, args);
+        final ent = vs.getelem(found, 0);
+        // Remove only the first matched entity. If nothing matches,
+        // succeed as a no-op rather than erroring.
+        if (null != ent) {
+          vs.delprop(entmap, vs.getprop(ent, 'id'));
+        }
+        return respond(fctx, 200);
+      } else if ('create' == op.name) {
+        self.buildArgs(fctx, op, fctx.reqdata);
+        dynamic id = param(fctx, 'id');
+        if (null == id) {
+          final rng = Random();
+          final h = () => rng.nextInt(0x10000).toRadixString(16);
+          id = (h() + h() + h() + h()).padRight(16, '0');
+        }
+
+        final ent = vs.clone(fctx.reqdata);
+        vs.setprop(ent, 'id', id);
+        vs.setprop(entmap, id, ent);
+        vs.delprop(ent, r'$KEY');
+        final out = vs.clone(ent);
+        return respond(fctx, 200, out);
+      }
+
+      return null;
+    }
+
+    // Optional network behaviour simulation over the mock transport. Enable
+    // per test via `SDK.test({ net: { latency, failTimes, ... } })`. When
+    // `net` is absent the mock behaves exactly as before (no wrapping), so
+    // existing generated tests are unaffected.
+    final net = options['net'];
+    ctx.utility.fetcher =
+        (null == net) ? testFetcher : makeNetsim(net, testFetcher);
+    return null;
+  }
+
+  // Wrap a transport with simulated network conditions: latency (fixed or
+  // {min,max}), a budget of first-N failures (`failTimes` -> `failStatus`),
+  // first-N connection errors (`errorTimes`), or a hard `offline` outage.
+  // Counter-driven, so simulations are deterministic across a test.
+  dynamic makeNetsim(dynamic net, dynamic inner) {
+    final self = this;
+    self._netcalls = 0;
+
+    int pickLatency() {
+      final l = net['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();
+      return max <= min ? min : min + ((max - min) >> 1);
+    }
+
+    Future<void> sleep(int ms) {
+      if (0 >= ms) {
+        return Future.value();
+      }
+      final sleeper = net['sleep'];
+      if (sleeper is Function) {
+        return Future.value(sleeper(ms)).then((_x) {});
+      }
+      return Future.delayed(Duration(milliseconds: ms));
+    }
+
+    return (dynamic fctx, dynamic url, dynamic fetchdef) async {
+      self._netcalls++;
+      final call = self._netcalls;
+
+      if (true == net['offline']) {
+        await sleep(pickLatency());
+        return fctx.error('netsim_offline',
+            'Simulated network offline (URL was: "' + url.toString() + '")');
+      }
+      final errorTimes = net['errorTimes'] is num ? net['errorTimes'] : 0;
+      if (call <= errorTimes) {
+        await sleep(pickLatency());
+        return fctx.error('netsim_conn',
+            'Simulated connection error (call ' + call.toString() + ')');
+      }
+      final failTimes = net['failTimes'] is num ? net['failTimes'] : 0;
+      if (call <= failTimes) {
+        await sleep(pickLatency());
+        final status = null == net['failStatus'] ? 503 : net['failStatus'];
+        return <String, dynamic>{
+          'status': status,
+          'statusText': 'Simulated Failure',
+          'body': 'not-used',
+          'json': () => null,
+          'headers': {},
+        };
+      }
+      await sleep(pickLatency());
+      return inner(fctx, url, fetchdef);
+    };
+  }
+
+  dynamic buildArgs(dynamic ctx, dynamic op, dynamic args) {
+    final param = ctx.utility.param;
+
+    final opname = op.name;
+
+    // Pick the entity's own endpoint from config, not a cross-reference from
+    // another resource that also returns it — the same rule makePoint falls
+    // back to, so the seed-data query is built from the endpoint the request
+    // will actually be sent to: a terminal `{id}` marks a record route, and
+    // failing that the shallower path wins.
+    final points = vs.getpath(
+        ctx.config, ['entity', _entname(ctx.entity), 'op', opname, 'points']);
+    var point = vs.getelem(points, 0);
+    if (points is List) {
+      int pointPartsLen(dynamic p) {
+        final parts = vs.getprop(p, 'parts');
+        return parts is List ? parts.length : 0;
+      }
+
+      bool pointTerminalParam(dynamic p) {
+        final parts = vs.getprop(p, 'parts');
+        if (parts is! List || parts.isEmpty) {
+          return false;
+        }
+        final last = parts[parts.length - 1];
+        return last is String && last.startsWith('{');
+      }
+
+      for (final cand in points) {
+        if (pointTerminalParam(cand) != pointTerminalParam(point)) {
+          if (pointTerminalParam(cand)) {
+            point = cand;
+          }
+        } else if (pointPartsLen(cand) < pointPartsLen(point)) {
+          point = cand;
+        }
+      }
+    }
+
+    final reqd = vs.transform(
+      vs.select(vs.getpath(point, ['args', 'params']), {'reqd': true}),
+      ['`\$EACH`', '', '`\$KEY.name`'],
+    );
+
+    final qand = <dynamic>[];
+    final q = {'`\$AND`': qand};
+
+    for (final k in vs.keysof(args)) {
+      if ('id' == k || !vs.isempty(vs.select(reqd, k))) {
+        final v = param(ctx, k);
+        // Dart's single null stands in for the donor's undefined: an
+        // absent match value constrains nothing.
+        if (null == v) {
+          continue;
+        }
+        // NOTE: mirrors the donor: op.alias is not present on Operation,
+        // so no alias alternates are generated here.
+        dynamic qor = [
+          {k: v}
+        ];
+
+        qor = {'`\$OR`': qor};
+
+        qand.add(qor);
+      }
+    }
+
+    if (null != ctx.ctrl['explain']) {
+      ctx.ctrl['explain']['test'] = {'query': q};
+    }
+
+    return q;
+  }
+
+  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/timeout/TimeoutFeature.dart

@@ -0,0 +1,104 @@
+// ignore_for_file: non_constant_identifier_names
+
+import 'dart:async';
+
+import '../../utility/ErrUtility.dart';
+
+import '../base/BaseFeature.dart';
+
+// Per-request timeout. Wraps the active transport and races each attempt
+// against a deadline; if the deadline wins, the request resolves to a
+// timeout error instead of hanging. The timer (`setTimer`/`clearTimer`)
+// is injectable so tests can drive the deadline deterministically; the
+// losing transport future is swallowed once the race is settled.
+class TimeoutFeature extends BaseFeature {
+  dynamic _client;
+
+  TimeoutFeature() {
+    version = '0.0.1';
+    name = 'timeout';
+    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._withTimeout(ctx2, url, fetchdef, inner);
+    };
+    return null;
+  }
+
+  Future<dynamic> _withTimeout(
+      dynamic ctx, dynamic url, dynamic fetchdef, dynamic inner) async {
+    final ms =
+        null == options['ms'] ? 30000 : (options['ms'] as num).toInt();
+    if (0 >= ms) {
+      return Future.value(inner(ctx, url, fetchdef));
+    }
+
+    final completer = Completer<dynamic>();
+
+    dynamic timer;
+    fire() {
+      if (!completer.isCompleted) {
+        completer.complete(ctx.error(
+            'timeout', 'Request exceeded timeout of ' + ms.toString() + 'ms'));
+      }
+    }
+
+    final schedule = options['setTimer'];
+    if (schedule is Function) {
+      timer = schedule(fire, ms);
+    } else {
+      timer = Timer(Duration(milliseconds: ms), fire);
+    }
+
+    Future.sync(() => inner(ctx, url, fetchdef)).then((res) {
+      if (!completer.isCompleted) {
+        completer.complete(res);
+      }
+    }, onError: (err, st) {
+      if (!completer.isCompleted) {
+        completer.completeError(err, st);
+      }
+      // Late transport failures after the deadline are swallowed.
+    });
+
+    try {
+      final res = await completer.future;
+
+      if (iserr(res) && 'timeout' == errcode(res)) {
+        _track(ctx, ms);
+      }
+
+      return res;
+    } finally {
+      final clear = options['clearTimer'];
+      if (clear is Function) {
+        clear(timer);
+      } else if (timer is Timer) {
+        timer.cancel();
+      }
+    }
+  }
+
+  void _track(dynamic ctx, int ms) {
+    final track = _client.track;
+    if (null == track['timeout']) {
+      track['timeout'] = <String, dynamic>{'count': 0, 'ms': ms};
+    }
+    track['timeout']['count']++;
+  }
+}

package/.sdk/tm/dart/lib/utility/CleanUtility.dart

@@ -0,0 +1,12 @@
+// Clean request data by partially hiding sensitive values.
+dynamic clean(dynamic ctx, dynamic val) {
+  // final options = ctx.options
+  // final cleankeyre = options?['__derived__']?['clean']?['keyre']
+  // final hintsize = 4
+
+  // NOTE: mirrors the donor (ts) implementation, where the masking pass is
+  // currently disabled; the derived clean.keyre is still computed by
+  // makeOptions so this can be enabled without an options change.
+
+  return val;
+}

package/.sdk/tm/dart/lib/utility/DoneUtility.dart

@@ -0,0 +1,18 @@
+import 'voxgig_struct.dart' as vs;
+
+import 'CleanUtility.dart';
+
+dynamic done(dynamic ctx) {
+  final error = ctx.utility.makeError;
+
+  if (null != ctx.ctrl['explain']) {
+    ctx.ctrl['explain'] = clean(ctx, ctx.ctrl['explain']);
+    vs.delprop(ctx.ctrl['explain']['result'], 'err');
+  }
+
+  if (null != ctx.result && true == ctx.result.ok) {
+    return ctx.result.resdata;
+  }
+
+  return error(ctx);
+}

package/.sdk/tm/dart/lib/utility/ErrUtility.dart

@@ -0,0 +1,46 @@
+// Error helpers for the ProjectName SDK.
+//
+// The donor (ts) pipeline distinguishes error values from results with
+// `instanceof Error`; Dart splits throwables into Error and Exception, so
+// `iserr` accepts both. `errmsg`/`errcode` read the conventional members
+// (message/code) from any error-ish value, falling back to toString().
+
+bool iserr(dynamic v) => v is Error || v is Exception;
+
+String errmsg(dynamic err) {
+  if (null == err) {
+    return 'unknown error';
+  }
+  if (err is Map) {
+    final m = err['message'];
+    return (m is String && '' != m) ? m : 'unknown error';
+  }
+  try {
+    final m = (err as dynamic).message;
+    if (m is String && '' != m) {
+      return m;
+    }
+  } catch (_e) {
+    // No message member: fall through to toString.
+  }
+  return err.toString();
+}
+
+String errcode(dynamic err) {
+  if (null == err) {
+    return '';
+  }
+  if (err is Map) {
+    final c = err['code'];
+    return c is String ? c : '';
+  }
+  try {
+    final c = (err as dynamic).code;
+    if (c is String) {
+      return c;
+    }
+  } catch (_e) {
+    // No code member.
+  }
+  return '';
+}

package/.sdk/tm/dart/lib/utility/FeatureAddUtility.dart

@@ -0,0 +1,35 @@
+void featureAdd(dynamic ctx, dynamic f) {
+  final client = ctx.client;
+
+  final dynamic rawopts = f.options;
+  final Map fopts = rawopts is Map ? rawopts : {};
+  var added = false;
+  final List features = client.features;
+
+  final before = fopts['__before__'];
+  final after = fopts['__after__'];
+  final repl = fopts['__replace__'];
+
+  if (null != before || null != after || null != repl) {
+    for (var i = 0; i < features.length; i++) {
+      final ef = features[i];
+      if (before == ef.name) {
+        features.insert(i, f);
+        added = true;
+        break;
+      } else if (after == ef.name) {
+        features.insert(i + 1, f);
+        added = true;
+        break;
+      } else if (repl == ef.name) {
+        features[i] = f;
+        added = true;
+        break;
+      }
+    }
+  }
+
+  if (!added) {
+    features.add(f);
+  }
+}

package/.sdk/tm/dart/lib/utility/FeatureHookUtility.dart

@@ -0,0 +1,20 @@
+import 'dart:async';
+
+dynamic featureHook(dynamic ctx, String name) {
+  final client = ctx.client;
+
+  final resp = <Future>[];
+  final List features = (null == client ? null : client.features) ?? [];
+
+  for (final f in features) {
+    final fres = f.invokeHook(name, ctx);
+    if (fres is Future) {
+      resp.add(fres);
+    }
+  }
+
+  if (0 < resp.length) {
+    return Future.wait(resp);
+  }
+  return null;
+}

package/.sdk/tm/dart/lib/utility/FeatureInitUtility.dart

@@ -0,0 +1,9 @@
+import 'voxgig_struct.dart' as vs;
+
+void featureInit(dynamic ctx, dynamic f) {
+  final fopts =
+      vs.getprop(vs.getprop(ctx.options, 'feature'), f.name) ?? {};
+  if (true == fopts['active']) {
+    f.init(ctx, fopts);
+  }
+}

package/.sdk/tm/dart/lib/utility/FetcherUtility.dart

@@ -0,0 +1,104 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'voxgig_struct.dart' as vs;
+
+// Make HTTP call using dart:io. Replace this utility for mocking etc.
+Future<dynamic> fetcher(dynamic ctx, dynamic fullurl, dynamic fetchdef) async {
+  if ('live' != ctx.client.mode) {
+    return ctx.error(
+        'fetch_mode_block',
+        'Request blocked by mode: "' +
+            ctx.client.mode.toString() +
+            '" (URL was: "' +
+            fullurl.toString() +
+            '")');
+  }
+
+  final options = ctx.client.options();
+
+  if (true == vs.getpath(options, 'feature.test.active')) {
+    return ctx.error(
+        'fetch_test_block',
+        'Request blocked as test feature is active' +
+            ' (URL was: "' +
+            fullurl.toString() +
+            '")');
+  }
+
+  final fetch = vs.getpath(options, 'system.fetch') ?? httpFetch;
+
+  final response = await Future.value(fetch(fullurl, fetchdef));
+
+  return response;
+}
+
+// Default live transport over dart:io HttpClient. Returns a transport-shaped
+// map: { status, statusText, headers, body, json } — the same shape as the
+// test feature's mock, so the result pipeline treats both identically.
+Future<dynamic> httpFetch(dynamic fullurl, dynamic fetchdef) async {
+  final client = HttpClient();
+  try {
+    final uri = Uri.parse(fullurl.toString());
+    final method =
+        (vs.getprop(fetchdef, 'method', 'GET') ?? 'GET').toString();
+
+    final req = await client.openUrl(method, uri);
+
+    // Manual redirects: fetchdef['redirect'] == 'manual' surfaces a 3xx as
+    // an ordinary response instead of auto-following it — HttpClient would
+    // otherwise replay the request, headers included, against whatever host
+    // Location names. Set by the station feature's transport middleware
+    // under an egress hosts policy (mirrors the ts fetch option).
+    if ('manual' == vs.getprop(fetchdef, 'redirect')) {
+      req.followRedirects = false;
+    }
+
+    final headers = vs.getprop(fetchdef, 'headers');
+    if (headers is Map) {
+      headers.forEach((k, v) {
+        if (null != v) {
+          req.headers.set(k.toString(), v.toString());
+        }
+      });
+    }
+
+    final body = vs.getprop(fetchdef, 'body');
+    if (null != body) {
+      if (null == req.headers.value('content-type')) {
+        req.headers.set('content-type', 'application/json');
+      }
+      req.write(body.toString());
+    }
+
+    final res = await req.close();
+    final text = await res.transform(utf8.decoder).join();
+
+    final hmap = <String, dynamic>{};
+    res.headers.forEach((name, values) {
+      hmap[name.toLowerCase()] = values.join(', ');
+    });
+
+    dynamic jsonBody() {
+      if ('' == text) {
+        return null;
+      }
+      try {
+        return jsonDecode(text);
+      } catch (_e) {
+        return null;
+      }
+    }
+
+    return {
+      'status': res.statusCode,
+      'statusText': res.reasonPhrase,
+      'headers': hmap,
+      'body': '' == text ? null : text,
+      'json': jsonBody,
+    };
+  } finally {
+    client.close(force: true);
+  }
+}