@voxgig/sdkgen 1.3.8 → 1.3.9

package/project/.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/project/.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/project/.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/project/.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/project/.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/project/.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/project/.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/project/.sdk/tm/dart/lib/utility/FetcherUtility.dart

@@ -0,0 +1,95 @@
+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);
+
+    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);
+  }
+}

package/project/.sdk/tm/dart/lib/utility/MakeContextUtility.dart

@@ -0,0 +1,6 @@
+import '../Context.dart';
+
+dynamic makeContext(dynamic ctxmap, [dynamic basectx]) {
+  final ctx = Context(ctxmap, basectx);
+  return ctx;
+}

package/project/.sdk/tm/dart/lib/utility/MakeErrorUtility.dart

@@ -0,0 +1,67 @@
+import '../ProjectNameError.dart';
+import '../Result.dart';
+
+import 'CleanUtility.dart';
+import 'ErrUtility.dart';
+
+dynamic makeError(dynamic ctx, [dynamic err]) {
+  final op = ctx.op;
+  final opname =
+      (null == op || null == op.name) ? 'unknown operation' : op.name;
+
+  final result = ctx.result ?? Result({});
+  result.ok = false;
+
+  final reserr = result.err;
+
+  err ??= reserr;
+  err ??= ctx.error('unknown', 'unknown error');
+
+  // TODO: project name should come from config
+  // avoids spurious changes between template and generated utility
+  // applies for all utility files
+  final msg = 'ProjectNameSDK: ' + opname.toString() + ': ' + errmsg(err);
+
+  ProjectNameError sdkerr;
+  if (err is ProjectNameError) {
+    sdkerr = err;
+    sdkerr.message = clean(ctx, msg);
+  } else {
+    final code = errcode(err);
+    sdkerr = ProjectNameError('' == code ? 'unknown' : code, clean(ctx, msg), ctx);
+  }
+
+  if (null != result.err) {
+    result.err = null;
+  }
+
+  final spec = ctx.spec;
+
+  if (null != ctx.ctrl['explain']) {
+    ctx.ctrl['explain']['err'] = {
+      'code': sdkerr.code,
+      'message': sdkerr.message,
+    };
+  }
+
+  sdkerr.result = clean(ctx, result);
+  sdkerr.spec = clean(ctx, spec);
+
+  ctx.ctrl['err'] = sdkerr;
+
+  // Fire PreUnexpected so observability features (metrics, telemetry, audit,
+  // debug) close/record error paths that never reach PreDone (e.g. a PrePoint
+  // rbac short-circuit). Fires after ctx.ctrl['err'] is set so hooks can read
+  // the error; features guard against double-recording when PreDone fired.
+  final utility = ctx.utility;
+  if (null != utility && null != utility.featureHook) {
+    utility.featureHook(ctx, 'PreUnexpected');
+  }
+
+  // TODO: model option to return instead
+  if (false == ctx.ctrl['throw']) {
+    return result.resdata;
+  } else {
+    throw sdkerr;
+  }
+}

package/project/.sdk/tm/dart/lib/utility/MakeFetchDefUtility.dart

@@ -0,0 +1,42 @@
+import '../Result.dart';
+
+import 'voxgig_struct.dart' as vs;
+
+import 'ErrUtility.dart';
+
+dynamic makeFetchDef(dynamic ctx) {
+  final spec = ctx.spec;
+  final utility = ctx.utility;
+  final makeUrl = utility.makeUrl;
+
+  if (null == spec) {
+    return ctx.error(
+        'fetchdef_no_spec', 'Expected context spec property to be defined.');
+  }
+
+  if (null == ctx.result) {
+    ctx.result = Result({});
+  }
+
+  spec.step = 'prepare';
+
+  final url = makeUrl(ctx);
+  if (iserr(url)) {
+    return url;
+  }
+
+  spec.url = url;
+
+  final fetchdef = <String, dynamic>{
+    'url': url,
+    'method': spec.method,
+    'headers': spec.headers,
+  };
+
+  if (null != spec.body) {
+    fetchdef['body'] =
+        vs.isnode(spec.body) ? vs.jsonify(spec.body) : spec.body;
+  }
+
+  return fetchdef;
+}

package/project/.sdk/tm/dart/lib/utility/MakeOptionsUtility.dart

@@ -0,0 +1,147 @@
+import 'voxgig_struct.dart' as vs;
+
+import 'FetcherUtility.dart';
+
+dynamic makeOptions(dynamic ctx) {
+  final utility = ctx.utility;
+  final options = ctx.options;
+
+  // Custom utility overrides.
+  final customUtils = vs.getprop(options, 'utility') ?? {};
+  for (final item in vs.items(customUtils)) {
+    utility.setUtility(item[0], item[1]);
+  }
+
+  final config = ctx.config ?? {};
+  final cfgopts = vs.getprop(config, 'options') ?? {};
+
+  // Standard SDK option values.
+  final optspec = {
+    'apikey': '',
+    'base': 'http://localhost:8000',
+    'prefix': '',
+    'suffix': '',
+    'auth': {
+      'prefix': '',
+    },
+    'headers': {
+      '`\$CHILD`': '`\$STRING`',
+    },
+    'allow': {
+      'method': 'GET,PUT,POST,PATCH,DELETE,OPTIONS',
+      'op': 'create,update,load,list,remove,command,direct',
+    },
+    'entity': {
+      '`\$CHILD`': {
+        '`\$OPEN`': true,
+        'active': false,
+        'alias': {},
+      },
+    },
+    'feature': {
+      '`\$CHILD`': {
+        '`\$OPEN`': true,
+        'active': false,
+      },
+    },
+    'utility': {},
+    'system': {},
+    'test': {
+      'active': false,
+      'entity': {
+        '`\$OPEN`': true,
+      },
+    },
+    'clean': {
+      'keys': 'key,token,id',
+    },
+  };
+
+  // Dart specific: preserve the (function-valued) system.fetch across
+  // merge/validate, defaulting to the dart:io transport.
+  final sysFetch = vs.getpath(options, 'system.fetch') ?? httpFetch;
+
+  // Feature add-order. `options.feature` may be given as an ordered List of
+  // { name, active, ...opts } entries (the List position IS the order in
+  // which features are added), or as a { name: {opts} } map. Normalize a
+  // List to a map (so merge/validate are unchanged) and remember the
+  // explicit order; a map defaults to test-first so the `test` mock
+  // transport is installed as the base of the transport wrapper chain.
+  final featureorder = <String>[];
+  dynamic mergeOptions = options ?? {};
+  final rawFeature = vs.getprop(options, 'feature');
+  if (rawFeature is List) {
+    final fmap = <String, dynamic>{};
+    for (final entry in rawFeature) {
+      if (entry is Map && null != vs.getprop(entry, 'name')) {
+        final fname = vs.getprop(entry, 'name').toString();
+        final fopts = <String, dynamic>{};
+        entry.forEach((k, v) {
+          if ('name' != k) {
+            fopts[k.toString()] = v;
+          }
+        });
+        fmap[fname] = fopts;
+        featureorder.add(fname);
+      }
+    }
+    mergeOptions = vs.clone(options);
+    mergeOptions['feature'] = fmap;
+  }
+
+  // User option maps are cloned first — their (possibly narrow) literal
+  // types must not constrain the merged structures.
+  dynamic opts = vs.merge([{}, cfgopts, vs.clone(mergeOptions)]);
+
+  opts = vs.validate(opts, optspec);
+
+  final sys = vs.getprop(opts, 'system');
+  if (sys is Map) {
+    sys['fetch'] = sysFetch;
+  } else {
+    opts['system'] = {'fetch': sysFetch};
+  }
+
+  final cleanKeys =
+      (vs.getpath(opts, 'clean.keys') ?? 'key,token,id').toString();
+
+  final parts = <String>[];
+  for (final part in cleanKeys.split(',')) {
+    final trimmed = part.trim();
+    if ('' != trimmed) {
+      parts.add(vs.escre(trimmed));
+    }
+  }
+  final keyre = parts.join('|');
+
+  // Resolve the feature add-order: an explicit List order (above) wins;
+  // otherwise order the map test-first, then the remaining names sorted, so
+  // the outcome is deterministic and `test` is always the base transport.
+  if (0 == featureorder.length) {
+    final featureMap = vs.getprop(opts, 'feature') ?? {};
+    final names = <String>[];
+    for (final it in vs.items(featureMap)) {
+      names.add(it[0].toString());
+    }
+    names.sort();
+    if (names.contains('test')) {
+      featureorder.add('test');
+      for (final n in names) {
+        if ('test' != n) {
+          featureorder.add(n);
+        }
+      }
+    } else {
+      featureorder.addAll(names);
+    }
+  }
+
+  opts['__derived__'] = {
+    'clean': {
+      'keyre': '' == keyre ? null : keyre,
+    },
+    'featureorder': featureorder,
+  };
+
+  return opts;
+}

package/project/.sdk/tm/dart/lib/utility/MakePointUtility.dart

@@ -0,0 +1,84 @@
+import 'voxgig_struct.dart' as vs;
+
+dynamic makePoint(dynamic ctx) {
+  if (null != ctx.out['point']) {
+    return ctx.point = ctx.out['point'];
+  }
+
+  final op = ctx.op;
+  final options = ctx.options;
+
+  final allowop = (vs.getpath(options, 'allow.op') ?? '').toString();
+  if (!allowop.contains(op.name.toString())) {
+    return ctx.error(
+        'point_op_allow',
+        'Operation "' +
+            op.name.toString() +
+            '" not allowed by SDK option allow.op value: "' +
+            allowop +
+            '"');
+  }
+
+  if (0 == op.points.length) {
+    return ctx.error(
+        'point_no_points',
+        'Operation "' + op.name.toString() + '" has no endpoint definitions.');
+  }
+
+  // Choose the appropriate point based on the match or data.
+  if (1 == op.points.length) {
+    ctx.point = op.points[0];
+  } else {
+    // Operation argument has priority, but also look in current data or match.
+    final reqselector = 'data' == op.input ? ctx.reqdata : ctx.reqmatch;
+    final selector = 'data' == op.input ? ctx.data : ctx.match;
+
+    dynamic point;
+    for (var i = 0; i < op.points.length; i++) {
+      point = op.points[i];
+      final select = point.select;
+      var found = true;
+
+      final exist = vs.getprop(select, 'exist');
+      if (null != selector && exist is List) {
+        for (var j = 0; j < exist.length; j++) {
+          final existkey = exist[j];
+
+          if (null == vs.getprop(reqselector, existkey) &&
+              null == vs.getprop(selector, existkey)) {
+            found = false;
+            break;
+          }
+        }
+      }
+
+      // Action is only in operation argument.
+      if (found &&
+          vs.getprop(reqselector, r'$action') !=
+              vs.getprop(select, r'$action')) {
+        found = false;
+      }
+
+      if (found) {
+        break;
+      }
+    }
+
+    if (null != vs.getprop(reqselector, r'$action') &&
+        null != point &&
+        vs.getprop(reqselector, r'$action') !=
+            vs.getprop(point.select, r'$action')) {
+      return ctx.error(
+          'point_action_invalid',
+          'Operation "' +
+              op.name.toString() +
+              '" action "' +
+              vs.getprop(reqselector, r'$action').toString() +
+              '" is not valid.');
+    }
+
+    ctx.point = point;
+  }
+
+  return ctx.point;
+}