fix(train): the firmware relay's calls to Polar time out, are bounded and limited per person (ADR 0030, D55)

Like BRouter's and Photon's: timeouts on connecting and reading, a check answer up to 64 KB and a file up to 64 MB, no redirect but to https, one fetch per file at a time, and 10 checks and downloads a minute for a person (tooOften). An answer that names no update properly is unreachable, no longer no update. The relay is the pod's, as routing's and search's.

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

apps/train/halkyon_train_server/lib/src/firmware/firmware_endpoint.dart

@@ -1,21 +1,9 @@
-import 'dart:io';
 import 'dart:typed_data';
 
 import 'package:halkyon_train_server/src/firmware/firmware_relay.dart';
 import 'package:halkyon_train_server/src/generated/protocol.dart';
 import 'package:serverpod/serverpod.dart';
-
-/// The relay the endpoint uses: Polar's own service; tests put a fake.
-FirmwareRelay firmwareRelay = FirmwareRelay(HttpPolarFirmwareService());
-
-/// Whether the instance relays firmware, as its environment says; tests
-/// set it.
-bool Function() firmwareRelayed = () => firmwareRelayedBy(Platform.environment);
-
-/// Whether [environment] has relaying on (D40): on unless
-/// `LOOP_FIRMWARE_RELAY` is `off`.
-bool firmwareRelayedBy(Map<String, String> environment) =>
-    environment['LOOP_FIRMWARE_RELAY']?.trim().toLowerCase() != 'off';
+import 'package:serverpod_auth_idp_server/core.dart';
 
 /// The Polar Loop's firmware through the instance (ADR 0030, D10, D40), for
 /// the people signed in: the instance asks Polar in their place, so Polar
@@ -25,7 +13,8 @@ class FirmwareEndpoint extends Endpoint {
   bool get requireLogin => true;
 
   /// Whether the instance relays firmware.
-  Future<bool> offered(Session session) async => firmwareRelayed();
+  Future<bool> offered(Session session) async =>
+      FirmwareRelay.of(session.serverpod).offered;
 
   /// The update for the band of [uuid] (Polar's UUID made from its ID) at
   /// [firmwareVersion] with [hardwareCode]; null where there is none.
@@ -34,31 +23,21 @@ class FirmwareEndpoint extends Endpoint {
     String uuid,
     String firmwareVersion,
     String hardwareCode,
-  ) async {
-    _offeredOrRefused();
-    return await firmwareRelay.check(
-      uuid: uuid,
-      firmwareVersion: firmwareVersion,
-      hardwareCode: hardwareCode,
-    );
-  }
+  ) => FirmwareRelay.of(session.serverpod).check(
+    session.authenticated!.authUserId,
+    uuid: uuid,
+    firmwareVersion: firmwareVersion,
+    hardwareCode: hardwareCode,
+  );
 
   /// The file of [version] for bands of [hardwareCode], as a check named it.
   Future<ByteData> download(
     Session session,
     String hardwareCode,
     String version,
-  ) async {
-    _offeredOrRefused();
-    return await firmwareRelay.download(
-      hardwareCode: hardwareCode,
-      version: version,
-    );
-  }
-
-  void _offeredOrRefused() {
-    if (!firmwareRelayed()) {
-      throw LoopFirmwareRefused(reason: 'off');
-    }
-  }
+  ) => FirmwareRelay.of(session.serverpod).download(
+    session.authenticated!.authUserId,
+    hardwareCode: hardwareCode,
+    version: version,
+  );
 }

apps/train/halkyon_train_server/lib/src/firmware/firmware_relay.dart

@@ -1,9 +1,12 @@
+import 'dart:async';
+import 'dart:collection';
 import 'dart:convert';
 import 'dart:io';
 import 'dart:typed_data';
 
 import 'package:clock/clock.dart';
 import 'package:halkyon_train_server/src/generated/protocol.dart';
+import 'package:serverpod/serverpod.dart';
 
 /// How long a firmware file is kept once fetched (D40).
 const _kept = Duration(days: 1);
@@ -23,10 +26,43 @@ abstract interface class PolarFirmwareService() {
   Future<Uint8List> fetch(Uri file);
 }
 
-/// [PolarFirmwareService] at `firmware-management.polar.com`, with the
-/// client name Polar's own SDK sends.
-class HttpPolarFirmwareService() implements PolarFirmwareService {
-  static final _base = Uri.parse('https://firmware-management.polar.com');
+/// Polar's firmware service didn't answer, or not as it does.
+final class PolarFailed implements Exception {
+  const PolarFailed(this.reason);
+
+  final String reason;
+
+  @override
+  String toString() => 'PolarFailed: $reason';
+}
+
+/// [PolarFirmwareService] at `firmware-management.polar.com` (tests: [base]),
+/// with the client name Polar's own SDK sends. Each wait is bounded by
+/// [timeout], each answer by its size, and no redirect leaves `https`.
+class HttpPolarFirmwareService implements PolarFirmwareService {
+  HttpPolarFirmwareService({
+    Uri? base,
+    this.timeout = const Duration(seconds: 10),
+  }) : base = base ?? Uri.parse('https://firmware-management.polar.com');
+
+  final Uri base;
+
+  /// The longest wait for a connection, an answer and each part of its body.
+  final Duration timeout;
+
+  /// The largest check answer: a version and an address are a few hundred
+  /// bytes.
+  static const maxAnswer = 64 * 1024;
+
+  /// The largest firmware file: the Loop's are a few megabytes, and each is
+  /// held in memory for a day (D40).
+  static const maxFile = 64 * 1024 * 1024;
+
+  /// The longest a file may take as a whole, however steadily it comes.
+  static const _wholeFile = Duration(minutes: 5);
+
+  /// The most redirects a file follows, each to `https` alone.
+  static const _redirects = 5;
 
   @override
   Future<({String version, Uri file})?> check({
@@ -34,79 +70,155 @@ class HttpPolarFirmwareService() implements PolarFirmwareService {
     required String firmwareVersion,
     required String hardwareCode,
   }) async {
-    final client = HttpClient();
+    final client = HttpClient()..connectionTimeout = timeout;
     try {
-      final request = await client.postUrl(
-        _base.resolve('/api/v1/firmware-update/check'),
-      );
-      request.headers
-        ..contentType = ContentType.json
-        ..set(HttpHeaders.acceptHeader, 'application/json');
-      request.write(
-        jsonEncode({
-          'clientId': 'polar-sensor-data-collector-android',
-          'uuid': uuid,
-          'firmwareVersion': firmwareVersion,
-          'hardwareCode': hardwareCode,
-        }),
-      );
-      final response = await request.close();
-      final body = await utf8.decodeStream(response);
+      final request = await client
+          .postUrl(base.resolve('/api/v1/firmware-update/check'))
+          .timeout(timeout);
+      request
+        ..followRedirects = false
+        ..headers.contentType = ContentType.json
+        ..headers.set(HttpHeaders.acceptHeader, 'application/json')
+        ..write(
+          jsonEncode({
+            'clientId': 'polar-sensor-data-collector-android',
+            'uuid': uuid,
+            'firmwareVersion': firmwareVersion,
+            'hardwareCode': hardwareCode,
+          }),
+        );
+      final response = await request.close().timeout(timeout);
       // No update is answered with no content (or not found).
       if (response.statusCode == HttpStatus.noContent ||
           response.statusCode == HttpStatus.notFound) {
         return null;
       }
       if (response.statusCode != HttpStatus.ok) {
-        throw HttpException('firmware check ${response.statusCode}');
+        throw PolarFailed('check ${response.statusCode}');
       }
+      final body = utf8.decode(
+        await _read(response, maxAnswer).timeout(timeout),
+      );
+      // An answer without both, or naming a file not over https, is a format
+      // Polar changed: not "no update".
       return switch (jsonDecode(body)) {
         {'version': final String version, 'fileUrl': final String file}
             when Uri.tryParse(file)?.isScheme('https') ?? false =>
           (version: version, file: Uri.parse(file)),
-        _ => null,
+        _ => throw const PolarFailed('check answer'),
       };
     } finally {
-      client.close();
+      client.close(force: true);
     }
   }
 
+  /// The file at [file], which [check] named over `https`, following its
+  /// redirects only where they stay on `https`.
   @override
   Future<Uint8List> fetch(Uri file) async {
-    final client = HttpClient();
+    final client = HttpClient()..connectionTimeout = timeout;
     try {
-      final response = await (await client.getUrl(file)).close();
-      if (response.statusCode != HttpStatus.ok) {
-        throw HttpException('firmware file ${response.statusCode}');
+      var at = file;
+      for (var redirects = 0; ; redirects++) {
+        final request = await client.getUrl(at).timeout(timeout);
+        request.followRedirects = false;
+        final response = await request.close().timeout(timeout);
+        if (response.isRedirect) {
+          final location = response.headers.value(HttpHeaders.locationHeader);
+          final next = location == null ? null : at.resolve(location);
+          if (next == null ||
+              !next.isScheme('https') ||
+              redirects >= _redirects) {
+            throw const PolarFailed('file redirect');
+          }
+          at = next;
+          continue;
+        }
+        if (response.statusCode != HttpStatus.ok) {
+          throw PolarFailed('file ${response.statusCode}');
+        }
+        return await _read(response, maxFile).timeout(_wholeFile);
       }
-      final bytes = BytesBuilder(copy: false);
-      await response.forEach(bytes.add);
-      return bytes.takeBytes();
     } finally {
-      client.close();
+      client.close(force: true);
     }
   }
+
+  /// [response]'s body, refused beyond [max] bytes (as soon as its length
+  /// says so) and where a part is longer than [timeout] in coming.
+  Future<Uint8List> _read(HttpClientResponse response, int max) async {
+    if (response.contentLength > max) {
+      throw const PolarFailed('too large');
+    }
+    final bytes = BytesBuilder(copy: false);
+    await for (final chunk in response.timeout(timeout)) {
+      if (bytes.length + chunk.length > max) {
+        throw const PolarFailed('too large');
+      }
+      bytes.add(chunk);
+    }
+    return bytes.takeBytes();
+  }
 }
 
+/// Whether [environment] has relaying on (D40): on unless
+/// `LOOP_FIRMWARE_RELAY` is `off`.
+bool firmwareRelayedBy(Map<String, String> environment) =>
+    environment['LOOP_FIRMWARE_RELAY']?.trim().toLowerCase() != 'off';
+
 /// The instance relaying Polar's firmware for its people (D40): it asks
-/// Polar in their place and fetches each file once for every band of its
-/// hardware, keeping it in memory for a day.
-class FirmwareRelay(final PolarFirmwareService _polar) {
+/// Polar in their place, as often as [perMinute] allows, and fetches each
+/// file once for every band of its hardware, keeping it in memory for a day.
+class FirmwareRelay {
+  FirmwareRelay(this._polar, {this.offered = true});
+
+  /// The relay of [pod], made the first time it is asked for: Polar's own
+  /// service, on unless the operator's `LOOP_FIRMWARE_RELAY` is `off`. Tests
+  /// set their own.
+  factory FirmwareRelay.of(Serverpod pod) => _ofPod[pod] ??= FirmwareRelay(
+    HttpPolarFirmwareService(),
+    offered: firmwareRelayedBy(Platform.environment),
+  );
+  static final _ofPod = Expando<FirmwareRelay>('FirmwareRelay');
+
+  /// Makes [relay] the one of [pod].
+  static void use(Serverpod pod, FirmwareRelay relay) => _ofPod[pod] = relay;
+
+  final PolarFirmwareService _polar;
+
+  /// Whether the instance relays firmware; off: everything is refused.
+  final bool offered;
+
+  /// The most checks and downloads a person may ask for in a minute: Train
+  /// checks once a day and when asked (D40), and downloads what it found, so
+  /// a few a minute are a person tapping *Check for updates* again; more
+  /// would have the instance ask Polar, or hand out files, for anyone.
+  static const perMinute = 10;
+
   /// The files Polar named, by hardware and version: where each is, and
   /// the file once fetched.
   final _files = <String, ({Uri file, Uint8List? bytes, DateTime at})>{};
 
-  /// The update for a band; null where Polar has none. Throws
-  /// [LoopFirmwareRefused] for figures it doesn't take, or where Polar
-  /// didn't answer.
-  Future<LoopFirmware?> check({
+  /// The fetches under way, by hardware and version, which those
+  /// downloading the same file meanwhile wait for.
+  final _fetching = <String, Future<Uint8List>>{};
+
+  final _asked = HashMap<UuidValue, Queue<DateTime>>();
+
+  /// The update for [person]'s band; null where Polar has none. Throws
+  /// [LoopFirmwareRefused] where relaying is off, for figures it doesn't
+  /// take, beyond [perMinute], or where Polar didn't answer as it does.
+  Future<LoopFirmware?> check(
+    UuidValue person, {
     required String uuid,
     required String firmwareVersion,
     required String hardwareCode,
   }) async {
+    _offeredOrRefused();
     if (!_valid(uuid) || !_valid(firmwareVersion) || !_valid(hardwareCode)) {
       throw LoopFirmwareRefused(reason: 'invalid');
     }
+    _count(person);
     final ({String version, Uri file})? update;
     try {
       update = await _polar.check(
@@ -129,13 +241,17 @@ class FirmwareRelay(final PolarFirmwareService _polar) {
     return LoopFirmware(version: update.version);
   }
 
-  /// The file of [version] for [hardwareCode], as a check named it; fetched
-  /// once and kept for a day. Throws [LoopFirmwareRefused] for one no check
-  /// named, or where Polar didn't answer.
-  Future<ByteData> download({
+  /// The file of [version] for [hardwareCode], as a check named it, for
+  /// [person]; fetched once, however many ask meanwhile, and kept for a day.
+  /// Throws [LoopFirmwareRefused] where relaying is off, beyond
+  /// [perMinute], for one no check named, or where Polar didn't answer.
+  Future<ByteData> download(
+    UuidValue person, {
     required String hardwareCode,
     required String version,
   }) async {
+    _offeredOrRefused();
+    _count(person);
     _forgetOld();
     final key = _key(hardwareCode, version);
     final known = _files[key];
@@ -147,14 +263,54 @@ class FirmwareRelay(final PolarFirmwareService _polar) {
     }
     final Uint8List bytes;
     try {
-      bytes = await _polar.fetch(known.file);
+      bytes = await (_fetching[key] ??= _fetch(key, known.file));
     } on Object {
       throw LoopFirmwareRefused(reason: 'unreachable');
     }
-    _files[key] = (file: known.file, bytes: bytes, at: clock.now());
     return ByteData.sublistView(bytes);
   }
 
+  /// Fetches [file] and keeps it under [key], unless a check named another
+  /// file there meanwhile.
+  Future<Uint8List> _fetch(String key, Uri file) async {
+    try {
+      final bytes = await _polar.fetch(file);
+      if (_files[key]?.file == file) {
+        _files[key] = (file: file, bytes: bytes, at: clock.now());
+      }
+      return bytes;
+    } finally {
+      unawaited(_fetching.remove(key));
+    }
+  }
+
+  void _offeredOrRefused() {
+    if (!offered) {
+      throw LoopFirmwareRefused(reason: 'off');
+    }
+  }
+
+  /// Counts a check or download of [person]'s, refusing it beyond
+  /// [perMinute] in the last minute.
+  void _count(UuidValue person) {
+    final now = clock.now();
+    final asked = _asked.putIfAbsent(person, Queue.new);
+    while (asked.isNotEmpty &&
+        now.difference(asked.first) >= const Duration(minutes: 1)) {
+      asked.removeFirst();
+    }
+    if (asked.length >= perMinute) {
+      throw LoopFirmwareRefused(reason: 'tooOften');
+    }
+    asked.addLast(now);
+    // Those who asked nothing for a minute are forgotten.
+    _asked.removeWhere(
+      (_, times) =>
+          times.isEmpty ||
+          now.difference(times.last) >= const Duration(minutes: 1),
+    );
+  }
+
   void _forgetOld() {
     final before = clock.now().subtract(_kept);
     _files.removeWhere((_, file) => file.at.isBefore(before));

apps/train/halkyon_train_server/lib/src/firmware/loop_firmware_refused.spy.yaml

@@ -1,7 +1,9 @@
 ### Why the instance relays no firmware (ADR 0030, D40): `off` where its
 ### operator turned relaying off, `invalid` for a band's figures it doesn't
 ### take, `unknown` for a file it wasn't told of (or no longer holds),
-### `unreachable` where Polar's service didn't answer.
+### `unreachable` where Polar's service didn't answer or answered with
+### something else than an update, `tooOften` beyond 10 checks and
+### downloads a minute for a person (D55).
 exception: LoopFirmwareRefused
 fields:
   reason: String

apps/train/halkyon_train_server/lib/src/generated/firmware/loop_firmware_refused.dart

@@ -15,7 +15,9 @@ import 'package:serverpod/serverpod.dart' as _is;
 /// Why the instance relays no firmware (ADR 0030, D40): `off` where its
 /// operator turned relaying off, `invalid` for a band's figures it doesn't
 /// take, `unknown` for a file it wasn't told of (or no longer holds),
-/// `unreachable` where Polar's service didn't answer.
+/// `unreachable` where Polar's service didn't answer or answered with
+/// something else than an update, `tooOften` beyond 10 checks and
+/// downloads a minute for a person (D55).
 abstract class LoopFirmwareRefused
     implements
         _is.SerializableException,