@githolon/dsl 0.113.4 → 0.115.0

package/dart/lib/src/rows_watch.dart

@@ -0,0 +1,390 @@
+import 'dart:async';
+import 'dart:collection';
+import 'dart:convert' show utf8;
+import 'dart:typed_data';
+
+import 'package:nomos_types/nomos_kernel_protocol.dart' as nomos_protocol;
+import 'package:nomos_types/src/proto/google/protobuf/any.pb.dart'
+    as google_protobuf;
+
+import 'generated_call.dart'
+    show NmsGeneratedResult, NmsInternalGeneratedResults;
+
+/// A row delta did not start where this watch's rows are (CAP-731).
+///
+/// The runtime composes every delta onto the position it last delivered, so a
+/// mismatch is a protocol defect, never a stale read to paper over. The watch
+/// ends with this error instead of guessing which rows it holds.
+final class NomosWatchPositionMismatch implements Exception {
+  const NomosWatchPositionMismatch({required this.held, required this.base});
+
+  /// The position of the rows this watch holds (`null`: no complete result yet).
+  final String? held;
+
+  /// The position the delta was computed from.
+  final String base;
+
+  @override
+  String toString() => 'NomosWatchPositionMismatch: the watch holds rows at '
+      '${held ?? '<no complete result>'} but was sent a delta from $base';
+}
+
+/// One emission of a rows watch: the rows in kernel order, plus what changed
+/// since this watch's previous emission (CAP-751).
+///
+/// It is the `List<T>` a rows watch has always emitted (read-only), so existing
+/// listeners are unaffected. A listener that keeps per-row work can use
+/// [changedIds] and [removedIds] to touch only those rows, or rely on identity:
+/// a row in neither set is the identical object it received last time.
+final class NomosRows<T> extends UnmodifiableListView<T> {
+  NomosRows._(
+    List<T> rows, {
+    required this.changedIds,
+    required this.removedIds,
+    required this.complete,
+  }) : super(rows);
+
+  /// Ids of the rows that are new, or whose object was replaced, since the
+  /// previous emission. Every id on the first emission.
+  final Set<String> changedIds;
+
+  /// Ids the previous emission held that this one does not.
+  final Set<String> removedIds;
+
+  /// Whether this emission came from a complete result (the first one, or the
+  /// first after a delivered failure) rather than from a row delta. The sets
+  /// are exact either way; a complete result usually replaces every row.
+  final bool complete;
+}
+
+/// The rows of one declared query, keyed by id and patched by kernel deltas.
+///
+/// Rows are kept in the kernel's order (ascending id by UTF-8 bytes, i.e. code
+/// points), so a merged result lists exactly what a complete read would. A row
+/// the update did not change keeps its identity, so a consumer can skip work on
+/// `identical(old, new)`.
+final class NmsRowsMerge<T> {
+  NmsRowsMerge({
+    required List<T> Function(NmsGeneratedResult result) decode,
+    required String Function(T row) idOf,
+  })  : _decode = decode,
+        _idOf = idOf;
+
+  final List<T> Function(NmsGeneratedResult result) _decode;
+  final String Function(T row) _idOf;
+  SplayTreeMap<String, T>? _rows;
+  String? _position;
+
+  /// The rows after [changed], or `null` when nothing this watch shows changed.
+  NomosRows<T>? apply(nomos_protocol.WatchChanged changed) {
+    if (changed.hasApplicationDelta()) {
+      return _applyDelta(changed.applicationDelta);
+    }
+    if (!changed.hasApplicationResult()) {
+      throw StateError('Generated watch returned no typed application result');
+    }
+    final previous = _rows;
+    final next = SplayTreeMap<String, T>(compareCodePoints);
+    final changedIds = <String>{};
+    for (final row in _decode(_result(changed.applicationResult))) {
+      final id = _idOf(row);
+      final held = previous?[id];
+      if (held != null && held == row) {
+        next[id] = held;
+      } else {
+        next[id] = row;
+        changedIds.add(id);
+      }
+    }
+    final removedIds = <String>{
+      if (previous != null)
+        for (final id in previous.keys)
+          if (!next.containsKey(id)) id,
+    };
+    _rows = next;
+    _position = changed.hasResultFrontier() ? changed.resultFrontier : null;
+    if (previous != null && changedIds.isEmpty && removedIds.isEmpty) {
+      return null;
+    }
+    return NomosRows<T>._(
+      List<T>.of(next.values, growable: false),
+      changedIds: changedIds,
+      removedIds: removedIds,
+      complete: true,
+    );
+  }
+
+  /// A failure delivered to the watch: whatever comes next must be complete.
+  void reset() {
+    _rows = null;
+    _position = null;
+  }
+
+  NomosRows<T>? _applyDelta(nomos_protocol.ApplicationResultDelta delta) {
+    final rows = _rows;
+    if (rows == null || _position == null || delta.baseFrontier != _position) {
+      throw NomosWatchPositionMismatch(
+          held: _position, base: delta.baseFrontier);
+    }
+    final removedIds = <String>{};
+    for (final id in delta.removedIds) {
+      if (rows.remove(id) != null) removedIds.add(id);
+    }
+    final changedIds = <String>{};
+    for (final row in _decode(_result(delta.changedRows))) {
+      final id = _idOf(row);
+      final held = rows[id];
+      if (held != null && held == row) continue;
+      rows[id] = row;
+      changedIds.add(id);
+      // Removed and re-added within one delta is a replacement, not a removal.
+      removedIds.remove(id);
+    }
+    _position = delta.frontier;
+    if (changedIds.isEmpty && removedIds.isEmpty) return null;
+    return NomosRows<T>._(
+      List<T>.of(rows.values, growable: false),
+      changedIds: changedIds,
+      removedIds: removedIds,
+      complete: false,
+    );
+  }
+
+  static NmsGeneratedResult _result(google_protobuf.Any any) =>
+      NmsInternalGeneratedResults.create(
+        protobufType: any.typeUrl,
+        protobufPayload: Uint8List.fromList(any.value),
+      );
+}
+
+/// Projects the rows of a rows watch into view models, calling the projection
+/// only for rows it has not seen (CAP-751).
+///
+/// A rows watch keeps every row the change did not touch as the identical
+/// object, so a row seen on the previous [apply] reuses its projection: one
+/// moved asset in a thousand costs one projection, not a thousand. A projection
+/// returning `null` leaves the row out. With an [order], the output is sorted by
+/// it, merging the few new projections into the previous order instead of
+/// sorting everything again; rows that compare equal have no defined order, so
+/// give a total order (for example by name, then id).
+///
+/// The projection must depend only on the row. When it also reads something
+/// else that changed (a lookup table, a setting), call [invalidate] so the next
+/// [apply] projects every row again.
+final class NomosRowProjection<T extends Object, R extends Object> {
+  NomosRowProjection(R? Function(T row) project, {Comparator<R>? order})
+      : _project = project,
+        _order = order;
+
+  final R? Function(T row) _project;
+  final Comparator<R>? _order;
+  HashMap<T, _Projected<R>> _seen = HashMap<T, _Projected<R>>.identity();
+  List<T>? _sources;
+  List<R>? _output;
+
+  /// [rows] projected. Returns the identical previous list when the output did
+  /// not change (every row was seen and none was added or left out anew).
+  List<R> apply(Iterable<T> rows) {
+    final seen = _seen;
+    final next = HashMap<T, _Projected<R>>.identity();
+    final sources = <T>[];
+    final output = <R>[];
+    final freshSources = <T>[];
+    final freshOutput = <R>[];
+    for (final row in rows) {
+      var projected = seen[row];
+      final fresh = projected == null;
+      projected ??= _Projected<R>(_project(row));
+      next[row] = projected;
+      final value = projected.value;
+      if (value == null) continue;
+      if (fresh) {
+        freshSources.add(row);
+        freshOutput.add(value);
+      } else {
+        sources.add(row);
+        output.add(value);
+      }
+    }
+    _seen = next;
+
+    final previousSources = _sources;
+    final previousOutput = _output;
+    final order = _order;
+    if (order == null) {
+      // Input order: rebuild in one pass when anything is new.
+      if (freshOutput.isEmpty &&
+          previousOutput != null &&
+          output.length == previousOutput.length) {
+        return previousOutput;
+      }
+      final all = <T>[];
+      final values = <R>[];
+      for (final row in rows) {
+        final value = next[row]!.value;
+        if (value == null) continue;
+        all.add(row);
+        values.add(value);
+      }
+      return _publish(all, values);
+    }
+
+    if (previousSources == null || previousOutput == null) {
+      final pairs = [
+        for (var i = 0; i < freshSources.length; i += 1)
+          (freshSources[i], freshOutput[i]),
+      ]..sort((a, b) => order(a.$2, b.$2));
+      return _publish([for (final p in pairs) p.$1], [for (final p in pairs) p.$2]);
+    }
+    // The kept rows are already in order: drop the ones that left, then merge
+    // in the new projections, sorted among themselves.
+    final keptSources = <T>[];
+    final keptOutput = <R>[];
+    for (var i = 0; i < previousSources.length; i += 1) {
+      final source = previousSources[i];
+      if (next.containsKey(source)) {
+        keptSources.add(source);
+        keptOutput.add(previousOutput[i]);
+      }
+    }
+    if (freshOutput.isEmpty && keptOutput.length == previousOutput.length) {
+      return previousOutput;
+    }
+    final fresh = [
+      for (var i = 0; i < freshSources.length; i += 1)
+        (freshSources[i], freshOutput[i]),
+    ]..sort((a, b) => order(a.$2, b.$2));
+    final mergedSources = <T>[];
+    final mergedOutput = <R>[];
+    var k = 0;
+    var f = 0;
+    while (k < keptOutput.length || f < fresh.length) {
+      final takeKept = f >= fresh.length ||
+          (k < keptOutput.length && order(keptOutput[k], fresh[f].$2) <= 0);
+      if (takeKept) {
+        mergedSources.add(keptSources[k]);
+        mergedOutput.add(keptOutput[k]);
+        k += 1;
+      } else {
+        mergedSources.add(fresh[f].$1);
+        mergedOutput.add(fresh[f].$2);
+        f += 1;
+      }
+    }
+    return _publish(mergedSources, mergedOutput);
+  }
+
+  /// Forget every projection: the next [apply] projects every row again.
+  void invalidate() {
+    _seen = HashMap<T, _Projected<R>>.identity();
+    _sources = null;
+    _output = null;
+  }
+
+  List<R> _publish(List<T> sources, List<R> output) {
+    _sources = sources;
+    return _output = List<R>.unmodifiable(output);
+  }
+}
+
+final class _Projected<R> {
+  _Projected(this.value);
+  final R? value;
+}
+
+/// Row projection for a stream of row lists, such as a generated rows watch
+/// (CAP-751). See [NomosRowProjection].
+extension NomosRowsProjectionStream<T extends Object> on Stream<List<T>> {
+  /// Each emission's rows projected with [project] (a `null` result leaves the
+  /// row out), optionally sorted by [order]. A row the watch did not change
+  /// reuses its earlier projection, and an emission whose output is unchanged
+  /// is not forwarded. Each listener keeps its own projections.
+  Stream<List<R>> projectRows<R extends Object>(
+    R? Function(T row) project, {
+    Comparator<R>? order,
+  }) {
+    final source = this;
+    return Stream<List<R>>.multi((controller) {
+      final projection = NomosRowProjection<T, R>(project, order: order);
+      List<R>? last;
+      final subscription = source.listen(
+        (rows) {
+          final List<R> output;
+          try {
+            output = projection.apply(rows);
+          } catch (error, stack) {
+            projection.invalidate();
+            controller.addErrorSync(error, stack);
+            return;
+          }
+          if (identical(output, last)) return;
+          last = output;
+          controller.addSync(output);
+        },
+        onError: controller.addErrorSync,
+        onDone: controller.closeSync,
+      );
+      controller
+        ..onPause = subscription.pause
+        ..onResume = subscription.resume
+        ..onCancel = subscription.cancel;
+    }, isBroadcast: source.isBroadcast);
+  }
+}
+
+/// Kernel row order: ascending UTF-8 bytes, which is ascending code points.
+/// Dart's [String.compareTo] orders UTF-16 code units and differs above the
+/// Basic Multilingual Plane.
+int compareCodePoints(String left, String right) {
+  if (left == right) return 0;
+  final a = utf8.encode(left);
+  final b = utf8.encode(right);
+  final length = a.length < b.length ? a.length : b.length;
+  for (var index = 0; index < length; index += 1) {
+    final order = a[index] - b[index];
+    if (order != 0) return order;
+  }
+  return a.length - b.length;
+}
+
+/// Merge a watch's complete results and deltas into row lists. Emits only when
+/// the rows changed. A delivered watch failure passes through and resets the
+/// rows; a position mismatch ends the stream with [NomosWatchPositionMismatch].
+Stream<List<T>> nmsMergeRows<T>(
+  Stream<nomos_protocol.WatchChanged> source,
+  NmsRowsMerge<T> merge,
+) {
+  late final StreamController<List<T>> controller;
+  StreamSubscription<nomos_protocol.WatchChanged>? upstream;
+  controller = StreamController<List<T>>(
+    onListen: () {
+      upstream = source.listen(
+        (changed) {
+          final List<T>? rows;
+          try {
+            rows = merge.apply(changed);
+          } on NomosWatchPositionMismatch catch (mismatch, stack) {
+            controller.addError(mismatch, stack);
+            unawaited(upstream?.cancel());
+            unawaited(controller.close());
+            return;
+          } catch (error, stack) {
+            merge.reset();
+            controller.addError(error, stack);
+            return;
+          }
+          if (rows != null) controller.add(rows);
+        },
+        onError: (Object error, StackTrace stack) {
+          merge.reset();
+          controller.addError(error, stack);
+        },
+        onDone: () => unawaited(controller.close()),
+      );
+    },
+    onPause: () => upstream?.pause(),
+    onResume: () => upstream?.resume(),
+    onCancel: () => upstream?.cancel(),
+  );
+  return controller.stream;
+}