@voxgig/sdkgen-langpack 0.0.1

package/.sdk/tm/dart/lib/Point.dart

@@ -0,0 +1,51 @@
+import 'utility/voxgig_struct.dart' as vs;
+
+class Point {
+  dynamic args;
+  // Transport this point speaks: 'http' (default) or 'graphql'. GraphQL
+  // points carry their operation document in `graphql` and address the
+  // single endpoint, so method is always POST and parts is empty.
+  dynamic kind;
+  dynamic graphql;
+  dynamic rename;
+  dynamic method;
+  dynamic orig;
+  dynamic parts;
+  dynamic params;
+  dynamic select;
+  dynamic active;
+  dynamic relations;
+  dynamic alias;
+  dynamic transform;
+
+  Point(dynamic altmap) {
+    args = vs.getprop(altmap, 'args', {'params': []});
+    kind = vs.getprop(altmap, 'kind', 'http');
+    graphql = vs.getprop(altmap, 'graphql');
+    rename = vs.getprop(altmap, 'rename', {'params': {}});
+    method = vs.getprop(altmap, 'method', '');
+    orig = vs.getprop(altmap, 'orig', '');
+    parts = vs.getprop(altmap, 'parts', []);
+    params = vs.getprop(altmap, 'params', []);
+    select = vs.getprop(altmap, 'select');
+    // Absent in config means ACTIVE: emission drops `active: true` as a default (sdkgen L0), so only an explicit `active: false` turns a point off.
+    active = vs.getprop(altmap, 'active', true);
+    relations = vs.getprop(altmap, 'relations', []);
+    alias = vs.getprop(altmap, 'alias', {});
+    transform = vs.getprop(altmap, 'transform', {'req': null, 'res': null});
+  }
+
+  Map<String, dynamic> toJSON() => {
+        'args': args,
+        'rename': rename,
+        'method': method,
+        'orig': orig,
+        'parts': parts,
+        'params': params,
+        'select': select,
+        'active': active,
+        'relations': relations,
+        'alias': alias,
+        'transform': transform,
+      };
+}

package/.sdk/tm/dart/lib/Response.dart

@@ -0,0 +1,32 @@
+import 'dart:async';
+
+import 'utility/voxgig_struct.dart' as vs;
+
+class Response {
+  dynamic status;
+  dynamic statusText;
+  dynamic headers;
+  dynamic jsonFn;
+  dynamic err;
+  dynamic body;
+
+  Response(dynamic resmap) {
+    status = vs.getprop(resmap, 'status', -1);
+    statusText = vs.getprop(resmap, 'statusText', '');
+    headers = vs.getprop(resmap, 'headers');
+    jsonFn = vs.getprop(resmap, 'json');
+    body = vs.getprop(resmap, 'body');
+    err = vs.getprop(resmap, 'err');
+  }
+
+  Future<dynamic> json() async =>
+      null == jsonFn ? null : await Future.value(jsonFn());
+
+  Map<String, dynamic> toJSON() => {
+        'status': status,
+        'statusText': statusText,
+        'headers': headers,
+        'body': body,
+        'err': err,
+      };
+}

package/.sdk/tm/dart/lib/Result.dart

@@ -0,0 +1,39 @@
+import 'utility/voxgig_struct.dart' as vs;
+
+class Result {
+  dynamic ok;
+  dynamic status;
+  dynamic statusText;
+  dynamic headers;
+  dynamic body;
+  dynamic err;
+  dynamic resdata;
+  dynamic resmatch;
+
+  // Feature extension slots (paging, streaming).
+  dynamic paging;
+  dynamic streaming;
+  dynamic stream;
+
+  Result(dynamic resmap) {
+    ok = vs.getprop(resmap, 'ok', false);
+    status = vs.getprop(resmap, 'status', -1);
+    statusText = vs.getprop(resmap, 'statusText', '');
+    headers = vs.getprop(resmap, 'headers', {});
+    body = vs.getprop(resmap, 'body');
+    err = vs.getprop(resmap, 'err');
+    resdata = vs.getprop(resmap, 'resdata');
+    resmatch = vs.getprop(resmap, 'resmatch');
+  }
+
+  Map<String, dynamic> toJSON() => {
+        'ok': ok,
+        'status': status,
+        'statusText': statusText,
+        'headers': headers,
+        'body': body,
+        'err': err,
+        'resdata': resdata,
+        'resmatch': resmatch,
+      };
+}

package/.sdk/tm/dart/lib/Spec.dart

@@ -0,0 +1,49 @@
+import 'utility/voxgig_struct.dart' as vs;
+
+class Spec {
+  dynamic parts;
+  dynamic headers;
+  dynamic alias;
+  dynamic base;
+  dynamic prefix;
+  dynamic suffix;
+  dynamic params;
+  dynamic query;
+  dynamic step;
+  dynamic method;
+  dynamic body;
+  dynamic url;
+  dynamic path;
+
+  Spec(dynamic specmap) {
+    parts = vs.getprop(specmap, 'parts', []);
+    headers = vs.getprop(specmap, 'headers', {});
+    alias = vs.getprop(specmap, 'alias', {});
+    base = vs.getprop(specmap, 'base', '');
+    prefix = vs.getprop(specmap, 'prefix', '');
+    suffix = vs.getprop(specmap, 'suffix', '');
+    params = vs.getprop(specmap, 'params', {});
+    query = vs.getprop(specmap, 'query', {});
+    step = vs.getprop(specmap, 'step', '');
+    method = vs.getprop(specmap, 'method', 'GET');
+    body = vs.getprop(specmap, 'body');
+    url = vs.getprop(specmap, 'url');
+    path = vs.getprop(specmap, 'path');
+  }
+
+  Map<String, dynamic> toJSON() => {
+        'parts': parts,
+        'headers': headers,
+        'alias': alias,
+        'base': base,
+        'prefix': prefix,
+        'suffix': suffix,
+        'params': params,
+        'query': query,
+        'step': step,
+        'method': method,
+        'body': body,
+        'url': url,
+        'path': path,
+      };
+}

package/.sdk/tm/dart/lib/feature/audit/AuditFeature.dart

@@ -0,0 +1,103 @@
+// ignore_for_file: non_constant_identifier_names
+
+import '../base/BaseFeature.dart';
+
+// Audit trail. Emits a structured record for every operation — who (actor),
+// what (entity + op), the outcome, and a correlation id — suitable for
+// compliance logging. Records accumulate on the client track
+// (`audit.records`, bounded by `max`) and, when a `sink` callback is
+// supplied, are also pushed to it (e.g. to forward to a SIEM). The actor is
+// taken from options (`actor`) or a per-call `ctrl.actor`. Timestamps use
+// the injectable `now` clock so tests stay deterministic.
+class AuditFeature extends BaseFeature {
+  dynamic _client;
+  int _seq = 0;
+  final Set<dynamic> _seen = {};
+
+  AuditFeature() {
+    version = '0.0.1';
+    name = 'audit';
+    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'];
+    _seq = 0;
+    _seen.clear();
+
+    final track = _client.track;
+    if (null == track['audit']) {
+      track['audit'] = <String, dynamic>{'records': <dynamic>[]};
+    }
+    return null;
+  }
+
+  @override
+  dynamic PreDone(dynamic ctx) {
+    // Outcome reflects the actual result; a non-2xx reaches PreDone before
+    // the pipeline throws.
+    _emit(
+        ctx,
+        (null != ctx.result &&
+                false != ctx.result.ok &&
+                null == ctx.result.err)
+            ? 'ok'
+            : 'error');
+    return null;
+  }
+
+  @override
+  dynamic PreUnexpected(dynamic ctx) {
+    _emit(ctx, 'error');
+    return null;
+  }
+
+  void _emit(dynamic ctx, String outcome) {
+    // One record per operation (PreDone + a following PreUnexpected on a
+    // non-2xx must not double-log).
+    if (_seen.contains(ctx)) {
+      return;
+    }
+    _seen.add(ctx);
+    _seq++;
+    final record = <String, dynamic>{
+      'seq': _seq,
+      'ts': _now(),
+      'actor': (ctx.ctrl is Map ? ctx.ctrl['actor'] : null) ??
+          options['actor'] ??
+          'anonymous',
+      'entity': null == ctx.op ? '_' : (ctx.op.entity ?? '_'),
+      'op': null == ctx.op ? '_' : (ctx.op.name ?? '_'),
+      'outcome': outcome,
+      'status': null == ctx.result ? null : ctx.result.status,
+      'correlationId': ctx.id,
+    };
+
+    final List recs = _client.track['audit']['records'];
+    recs.add(record);
+    final max = null == options['max'] ? 1000 : (options['max'] as num).toInt();
+    while (recs.length > max) {
+      recs.removeAt(0);
+    }
+
+    final sink = options['sink'];
+    if (sink is Function) {
+      try {
+        sink(record);
+      } catch (_e) {
+        // Sink failures are swallowed.
+      }
+    }
+  }
+
+  num _now() {
+    final now = options['now'];
+    if (now is Function) {
+      return now();
+    }
+    return DateTime.now().millisecondsSinceEpoch;
+  }
+}

package/.sdk/tm/dart/lib/feature/base/BaseFeature.dart

@@ -0,0 +1,76 @@
+// Base feature class implementing every pipeline hook as a no-op.
+// Features subclass this and override the hooks they need. Hook dispatch is
+// by name (see FeatureHookUtility), routed through `invokeHook` since Dart
+// has no dynamic property access.
+
+// ignore_for_file: non_constant_identifier_names
+
+class BaseFeature {
+  String version = '0.0.1';
+  String name = 'base';
+  bool active = true;
+
+  // Feature options as passed to init (used by featureAdd ordering).
+  Map<String, dynamic> options = {};
+
+  dynamic init(dynamic ctx, dynamic opts) {}
+
+  dynamic PostConstruct(dynamic ctx) {}
+
+  dynamic PostConstructEntity(dynamic ctx) {}
+
+  dynamic SetData(dynamic ctx) {}
+
+  dynamic GetData(dynamic ctx) {}
+
+  dynamic SetMatch(dynamic ctx) {}
+
+  dynamic GetMatch(dynamic ctx) {}
+
+  dynamic PrePoint(dynamic ctx) {}
+
+  dynamic PreSpec(dynamic ctx) {}
+
+  dynamic PreRequest(dynamic ctx) {}
+
+  dynamic PreResponse(dynamic ctx) {}
+
+  dynamic PreResult(dynamic ctx) {}
+
+  dynamic PreDone(dynamic ctx) {}
+
+  dynamic PreUnexpected(dynamic ctx) {}
+
+  dynamic invokeHook(String hook, dynamic ctx) {
+    switch (hook) {
+      case 'PostConstruct':
+        return PostConstruct(ctx);
+      case 'PostConstructEntity':
+        return PostConstructEntity(ctx);
+      case 'SetData':
+        return SetData(ctx);
+      case 'GetData':
+        return GetData(ctx);
+      case 'SetMatch':
+        return SetMatch(ctx);
+      case 'GetMatch':
+        return GetMatch(ctx);
+      case 'PrePoint':
+        return PrePoint(ctx);
+      case 'PreSpec':
+        return PreSpec(ctx);
+      case 'PreRequest':
+        return PreRequest(ctx);
+      case 'PreResponse':
+        return PreResponse(ctx);
+      case 'PreResult':
+        return PreResult(ctx);
+      case 'PreDone':
+        return PreDone(ctx);
+      case 'PreUnexpected':
+        return PreUnexpected(ctx);
+      default:
+        return null;
+    }
+  }
+}

package/.sdk/tm/dart/lib/feature/cache/CacheFeature.dart

@@ -0,0 +1,152 @@
+// ignore_for_file: non_constant_identifier_names
+
+import 'dart:async';
+
+import '../../utility/ErrUtility.dart';
+import '../../utility/voxgig_struct.dart' as vs;
+
+import '../base/BaseFeature.dart';
+
+// Response caching for safe (read) requests. Wraps the active transport and
+// serves a fresh cached snapshot instead of hitting the network when the
+// same method+URL was fetched within `ttl` ms. Only successful responses to
+// cacheable methods (default: GET) are stored, keyed by method+URL. The
+// cache is bounded (`max` entries, oldest evicted) and every hit/miss is
+// recorded on the client track for inspection. One-shot response bodies are
+// normalised on capture so both the current caller and later hits can read
+// the JSON body repeatedly.
+class CacheFeature extends BaseFeature {
+  dynamic _client;
+  final Map<String, dynamic> _store = {};
+
+  CacheFeature() {
+    version = '0.0.1';
+    name = 'cache';
+    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;
+    }
+
+    _store.clear();
+
+    final self = this;
+    final utility = ctx.utility;
+    final inner = utility.fetcher;
+
+    utility.fetcher = (dynamic ctx2, dynamic url, dynamic fetchdef) async {
+      return self._through(ctx2, url, fetchdef, inner);
+    };
+    return null;
+  }
+
+  Future<dynamic> _through(
+      dynamic ctx, dynamic url, dynamic fetchdef, dynamic inner) async {
+    final method =
+        (vs.getprop(fetchdef, 'method', 'GET') ?? 'GET').toString().toUpperCase();
+    final methods = options['methods'] ?? ['GET'];
+
+    if (!(methods as List).contains(method)) {
+      return inner(ctx, url, fetchdef);
+    }
+
+    final key = method + ' ' + url.toString();
+    final now = _now();
+    final hit = _store[key];
+
+    if (null != hit && hit['expiry'] > now) {
+      _track('hit');
+      return _replay(hit['snapshot']);
+    }
+
+    final res = await Future.value(inner(ctx, url, fetchdef));
+
+    if (_cacheable(res)) {
+      final snapshot = await _snapshot(res);
+      final ttl = null == options['ttl'] ? 5000 : options['ttl'];
+      _evict();
+      _store[key] = <String, dynamic>{'expiry': now + ttl, 'snapshot': snapshot};
+      _track('miss');
+      return _replay(snapshot);
+    }
+
+    _track('bypass');
+    return res;
+  }
+
+  bool _cacheable(dynamic res) {
+    if (null == res || iserr(res)) {
+      return false;
+    }
+    final status = vs.getprop(res, 'status');
+    return status is num && status >= 200 && status < 300;
+  }
+
+  Future<dynamic> _snapshot(dynamic res) async {
+    dynamic data;
+    final jsonFn = vs.getprop(res, 'json');
+    if (jsonFn is Function) {
+      try {
+        data = await Future.value(jsonFn());
+      } catch (_e) {
+        data = null;
+      }
+    }
+    final headers = <String, dynamic>{};
+    final rh = vs.getprop(res, 'headers');
+    if (rh is Map) {
+      rh.forEach((k, v) => headers[k.toString()] = v);
+    }
+    return <String, dynamic>{
+      'status': vs.getprop(res, 'status'),
+      'statusText': vs.getprop(res, 'statusText'),
+      'data': data,
+      'headers': headers,
+    };
+  }
+
+  dynamic _replay(dynamic snapshot) {
+    final headers = snapshot['headers'] ?? {};
+    final data = snapshot['data'];
+    return <String, dynamic>{
+      'status': snapshot['status'],
+      'statusText': snapshot['statusText'],
+      'body': 'not-used',
+      'json': () => data,
+      'headers': headers,
+    };
+  }
+
+  void _evict() {
+    final max = null == options['max'] ? 256 : (options['max'] as num).toInt();
+    while (_store.length >= max) {
+      if (_store.isEmpty) {
+        break;
+      }
+      _store.remove(_store.keys.first);
+    }
+  }
+
+  num _now() {
+    final now = options['now'];
+    if (now is Function) {
+      return now();
+    }
+    return DateTime.now().millisecondsSinceEpoch;
+  }
+
+  void _track(String kind) {
+    final track = _client.track;
+    if (null == track['cache']) {
+      track['cache'] = <String, dynamic>{'hit': 0, 'miss': 0, 'bypass': 0};
+    }
+    track['cache'][kind]++;
+  }
+}

package/.sdk/tm/dart/lib/feature/clienttrack/ClienttrackFeature.dart

@@ -0,0 +1,104 @@
+// ignore_for_file: non_constant_identifier_names
+
+import 'dart:math';
+
+import '../base/BaseFeature.dart';
+
+// Client tracking. Establishes a stable per-client session id at
+// construction and stamps identifying headers on every request: a
+// `User-Agent`, an `X-Client-Id` (session), and a fresh per-request
+// `X-Request-Id`. This lets a server correlate all traffic from one SDK
+// instance and each individual call. Header names, client name/version and
+// the id generator are configurable; the session id and request counter are
+// exposed on the client track (`clienttrack`).
+class ClienttrackFeature extends BaseFeature {
+  dynamic _client;
+  String _session = '';
+  int _requests = 0;
+
+  ClienttrackFeature() {
+    version = '0.0.1';
+    name = 'clienttrack';
+    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'];
+    _requests = 0;
+    return null;
+  }
+
+  @override
+  dynamic PostConstruct(dynamic ctx) {
+    _session = (options['sessionId'] ?? _genid('session')).toString();
+    _client.track['clienttrack'] = <String, dynamic>{
+      'session': _session,
+      'requests': 0,
+      'clientName': _name(),
+    };
+    return null;
+  }
+
+  @override
+  dynamic PreRequest(dynamic ctx) {
+    final spec = ctx.spec;
+    if (null == spec) {
+      return null;
+    }
+    spec.headers ??= {};
+    if ('' == _session) {
+      _session = (options['sessionId'] ?? _genid('session')).toString();
+    }
+
+    final h = options['headers'] ?? {};
+    _requests++;
+    final requestId = _genid('request');
+
+    _set(spec.headers, (h['agent'] ?? 'User-Agent').toString(), _name());
+    _set(spec.headers, (h['client'] ?? 'X-Client-Id').toString(), _session);
+    spec.headers[h['request'] ?? 'X-Request-Id'] = requestId;
+
+    final track = _client.track;
+    if (null == track['clienttrack']) {
+      track['clienttrack'] = <String, dynamic>{
+        'session': _session,
+        'requests': 0,
+        'clientName': _name(),
+      };
+    }
+    track['clienttrack']['requests'] = _requests;
+    track['clienttrack']['lastRequestId'] = requestId;
+    return null;
+  }
+
+  // Do not clobber a caller-provided value (e.g. a custom User-Agent).
+  void _set(dynamic headers, String name, String value) {
+    final lower = name.toLowerCase();
+    for (final k in (headers as Map).keys) {
+      if (k.toString().toLowerCase() == lower) {
+        return;
+      }
+    }
+    headers[name] = value;
+  }
+
+  String _name() {
+    final name = options['clientName'] ?? 'ProjectName-SDK';
+    final version = options['clientVersion'] ?? '0.0.1';
+    return name.toString() + '/' + version.toString();
+  }
+
+  String _genid(String kind) {
+    final idgen = options['idgen'];
+    if (idgen is Function) {
+      return idgen(kind).toString();
+    }
+    final rng = Random();
+    final h = () => rng.nextInt(0x8000000).toRadixString(16);
+    final id = kind.substring(0, 1) + '-' + h() + h() + h();
+    return id.length > 20 ? id.substring(0, 20) : id;
+  }
+}