feat(train): routes planned through the instance's BRouter (ADR 0030, D44)

The routing endpoint plans a route through the waypoints for one of six
profiles, for the people signed in, at most 50 waypoints and 30 plans a
person a minute, nothing kept or logged; refused without BROUTER_URL.
BRouter's GeoJSON is read into points, elevations, climb and descent
above 3 m, turn hints and stretches by surface. Train's running profile
for BRouter, halkyon-run.brf, is a first guess not yet tried on BRouter.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>

apps/train/halkyon_train_server/test/integration/routing/routing_endpoint_test.dart

@@ -0,0 +1,147 @@
+import 'package:clock/clock.dart';
+import 'package:halkyon_train_server/src/generated/protocol.dart';
+import 'package:halkyon_train_server/src/routing/brouter.dart';
+import 'package:halkyon_train_server/src/routing/routing.dart';
+import 'package:serverpod/serverpod.dart';
+import 'package:test/test.dart';
+
+import '../../unit/routing/brouter_test.dart' show brouterRoute;
+import '../test_tools/serverpod_test_tools.dart';
+
+/// BRouter as the tests want it: what it answers, and what it was asked.
+class _FakeBRouter implements RoutePlanner {
+  final asked = <(List<RoutePoint>, RouteProfile)>[];
+  Exception? failure;
+
+  @override
+  Future<Map<String, Object?>> route(
+    List<RoutePoint> waypoints,
+    RouteProfile profile,
+  ) async {
+    asked.add((waypoints, profile));
+    if (failure case final failure?) {
+      throw failure;
+    }
+    return brouterRoute();
+  }
+}
+
+Matcher _refused(String reason) =>
+    throwsA(isA<RouteRefused>().having((r) => r.reason, 'reason', reason));
+
+/// Routes planned by the instance's BRouter (ADR 0030, D11, D44): for the
+/// people signed in, where the instance has one, within a limit a minute.
+void main() {
+  withServerpod('Planning routes', (sessionBuilder, endpoints) {
+    late _FakeBRouter brouter;
+    final alice = sessionBuilder.copyWith(
+      authentication: AuthenticationOverride.authenticationInfo(
+        const Uuid().v7(),
+        {},
+      ),
+    );
+    final bob = sessionBuilder.copyWith(
+      authentication: AuthenticationOverride.authenticationInfo(
+        const Uuid().v7(),
+        {},
+      ),
+    );
+    final there = [
+      RoutePoint(lat: 52.52, lon: 13.40),
+      RoutePoint(lat: 52.53, lon: 13.41),
+    ];
+
+    void useRouting(Routing routing) =>
+        Routing.use(sessionBuilder.build().serverpod, routing);
+
+    setUp(() {
+      brouter = _FakeBRouter();
+      useRouting(Routing(router: brouter));
+    });
+
+    test(
+      'plans a route for someone signed in, with the profile asked',
+      () async {
+        expect(await endpoints.routing.offered(alice), isTrue);
+        final route = await endpoints.routing.plan(
+          alice,
+          there,
+          RouteProfile.gravel,
+        );
+
+        expect(route.distanceMetres, 1234);
+        expect(brouter.asked.single.$2, RouteProfile.gravel);
+      },
+    );
+
+    test('plans nothing for someone not signed in', () async {
+      await expectLater(
+        endpoints.routing.plan(sessionBuilder, there, RouteProfile.run),
+        throwsA(isA<ServerpodUnauthenticatedException>()),
+      );
+      await expectLater(
+        endpoints.routing.offered(sessionBuilder),
+        throwsA(isA<ServerpodUnauthenticatedException>()),
+      );
+      expect(brouter.asked, isEmpty);
+    });
+
+    test('without a BRouter it offers none, and refuses', () async {
+      useRouting(Routing());
+
+      expect(await endpoints.routing.offered(alice), isFalse);
+      await expectLater(
+        endpoints.routing.plan(alice, there, RouteProfile.run),
+        _refused('off'),
+      );
+    });
+
+    test('refuses fewer than two waypoints, too many, and points off the '
+        'earth, asking BRouter nothing', () async {
+      for (final waypoints in [
+        [there.first],
+        [for (var i = 0; i <= Routing.maxWaypoints; i++) there.first],
+        [there.first, RoutePoint(lat: 91, lon: 0)],
+        [there.first, RoutePoint(lat: 0, lon: 181)],
+      ]) {
+        await expectLater(
+          endpoints.routing.plan(alice, waypoints, RouteProfile.run),
+          _refused('invalid'),
+        );
+      }
+      expect(brouter.asked, isEmpty);
+    });
+
+    test('refuses a person beyond the plans of a minute, not others, and '
+        'plans again a minute later', () async {
+      var now = DateTime.utc(2026, 10, 28, 12);
+      await withClock(Clock(() => now), () async {
+        for (var i = 0; i < Routing.perMinute; i++) {
+          await endpoints.routing.plan(alice, there, RouteProfile.run);
+        }
+        await expectLater(
+          endpoints.routing.plan(alice, there, RouteProfile.run),
+          _refused('tooOften'),
+        );
+        await endpoints.routing.plan(bob, there, RouteProfile.run);
+
+        now = now.add(const Duration(minutes: 1));
+        await endpoints.routing.plan(alice, there, RouteProfile.run);
+      });
+    });
+
+    test('says where BRouter found no route, or did not answer', () async {
+      brouter.failure = NoRoute();
+      await expectLater(
+        endpoints.routing.plan(alice, there, RouteProfile.run),
+        _refused('noRoute'),
+      );
+
+      brouter.failure = BRouterFailed('down');
+      await expectLater(
+        endpoints.routing.plan(alice, there, RouteProfile.run),
+        _refused('unreachable'),
+      );
+    });
+  });
+}