feat(train): the Loop's firmware updates, directly or through the instance (ADR 0030, D10, D40)

Train's server relays Polar's firmware service for the people signed in
(`firmware`: offered, check, download), a fetched file kept in memory a
day per hardware and version, off with LOOP_FIRMWARE_RELAY=off. The app
asks on the day's first connection and on the band's screen, from Polar
or the instance as the person chose, never Polar in the instance's
place; an update runs only after asking, reads and keeps the band
first, and sets it up again with its figures and clock after.

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

apps/train/halkyon_train_server/test/integration/firmware/firmware_endpoint_test.dart

@@ -0,0 +1,209 @@
+import 'dart:typed_data';
+
+import 'package:clock/clock.dart';
+
+import 'package:halkyon_train_server/src/firmware/firmware_endpoint.dart';
+import 'package:halkyon_train_server/src/firmware/firmware_relay.dart';
+import 'package:halkyon_train_server/src/generated/protocol.dart';
+import 'package:serverpod/serverpod.dart';
+import 'package:test/test.dart';
+
+import '../test_tools/serverpod_test_tools.dart';
+
+/// Polar's firmware service as the tests want it: what it answers, and how
+/// often it was asked.
+class _FakePolar() implements PolarFirmwareService {
+  ({String version, Uri file})? update = (
+    version: '3.1.2',
+    file: Uri.parse('https://files.example/loop-3.1.2.zip'),
+  );
+  int checks = 0;
+  int fetches = 0;
+  bool down = false;
+
+  @override
+  Future<({String version, Uri file})?> check({
+    required String uuid,
+    required String firmwareVersion,
+    required String hardwareCode,
+  }) async {
+    checks++;
+    if (down) {
+      throw StateError('down');
+    }
+    return update;
+  }
+
+  @override
+  Future<Uint8List> fetch(Uri file) async {
+    fetches++;
+    return Uint8List.fromList([1, 2, 3]);
+  }
+}
+
+/// The Loop's firmware through the instance (ADR 0030, D10, D40): for the
+/// people signed in, unless the operator turned it off; each file fetched
+/// once for every band of its hardware.
+void main() {
+  withServerpod('Relaying the Loop firmware', (sessionBuilder, endpoints) {
+    late _FakePolar polar;
+    final signedIn = sessionBuilder.copyWith(
+      authentication: AuthenticationOverride.authenticationInfo(
+        const Uuid().v7(),
+        {},
+      ),
+    );
+
+    setUp(() {
+      polar = _FakePolar();
+      firmwareRelay = FirmwareRelay(polar);
+      firmwareRelayed = () => true;
+    });
+
+    test('names an update to someone signed in, and hands its file', () async {
+      final update = await endpoints.firmware.check(
+        signedIn,
+        'uuid-1',
+        '3.0.0',
+        'HW-1',
+      );
+
+      expect(update?.version, '3.1.2');
+      final file = await endpoints.firmware.download(signedIn, 'HW-1', '3.1.2');
+      expect(Uint8List.sublistView(file), [1, 2, 3]);
+    });
+
+    test('names none where Polar has none', () async {
+      polar.update = null;
+
+      expect(
+        await endpoints.firmware.check(signedIn, 'uuid-1', '3.1.2', 'HW-1'),
+        isNull,
+      );
+    });
+
+    test('fetches a file once for every band of its hardware', () async {
+      await endpoints.firmware.check(signedIn, 'uuid-1', '3.0.0', 'HW-1');
+      await endpoints.firmware.check(signedIn, 'uuid-2', '3.0.1', 'HW-1');
+      await endpoints.firmware.download(signedIn, 'HW-1', '3.1.2');
+      await endpoints.firmware.download(signedIn, 'HW-1', '3.1.2');
+
+      expect(polar.fetches, 1);
+    });
+
+    test('hands no file a check never named', () async {
+      await expectLater(
+        endpoints.firmware.download(signedIn, 'HW-9', '9.9.9'),
+        throwsA(
+          isA<LoopFirmwareRefused>().having(
+            (e) => e.reason,
+            'reason',
+            'unknown',
+          ),
+        ),
+      );
+      expect(polar.fetches, 0);
+    });
+
+    test("takes no figures that aren't a band's, and doesn't ask Polar "
+        'with them', () async {
+      await expectLater(
+        endpoints.firmware.check(signedIn, 'uuid 1/../x', '3.0.0', 'HW-1'),
+        throwsA(
+          isA<LoopFirmwareRefused>().having(
+            (e) => e.reason,
+            'reason',
+            'invalid',
+          ),
+        ),
+      );
+      expect(polar.checks, 0);
+    });
+
+    test("says Polar didn't answer", () async {
+      polar.down = true;
+
+      await expectLater(
+        endpoints.firmware.check(signedIn, 'uuid-1', '3.0.0', 'HW-1'),
+        throwsA(
+          isA<LoopFirmwareRefused>().having(
+            (e) => e.reason,
+            'reason',
+            'unreachable',
+          ),
+        ),
+      );
+    });
+
+    test(
+      'relays nothing where the operator turned it off, and says so',
+      () async {
+        firmwareRelayed = () => false;
+
+        expect(await endpoints.firmware.offered(signedIn), isFalse);
+        await expectLater(
+          endpoints.firmware.check(signedIn, 'uuid-1', '3.0.0', 'HW-1'),
+          throwsA(
+            isA<LoopFirmwareRefused>().having((e) => e.reason, 'reason', 'off'),
+          ),
+        );
+        await expectLater(
+          endpoints.firmware.download(signedIn, 'HW-1', '3.1.2'),
+          throwsA(isA<LoopFirmwareRefused>()),
+        );
+        expect(polar.checks, 0);
+      },
+    );
+
+    test('relays nothing to nobody signed in', () async {
+      final nobody = sessionBuilder.copyWith(
+        authentication: AuthenticationOverride.unauthenticated(),
+      );
+
+      await expectLater(
+        endpoints.firmware.offered(nobody),
+        throwsA(isA<ServerpodUnauthenticatedException>()),
+      );
+      await expectLater(
+        endpoints.firmware.check(nobody, 'uuid-1', '3.0.0', 'HW-1'),
+        throwsA(isA<ServerpodUnauthenticatedException>()),
+      );
+      await expectLater(
+        endpoints.firmware.download(nobody, 'HW-1', '3.1.2'),
+        throwsA(isA<ServerpodUnauthenticatedException>()),
+      );
+      expect(polar.checks, 0);
+    });
+  });
+
+  test('the operator turns relaying off with LOOP_FIRMWARE_RELAY=off', () {
+    expect(firmwareRelayedBy({}), isTrue);
+    expect(firmwareRelayedBy({'LOOP_FIRMWARE_RELAY': 'on'}), isTrue);
+    expect(firmwareRelayedBy({'LOOP_FIRMWARE_RELAY': ' OFF '}), isFalse);
+  });
+
+  test('a file is kept a day, then fetched again after a new check', () async {
+    final polar = _FakePolar();
+    final relay = FirmwareRelay(polar);
+    var now = DateTime.utc(2026, 10, 28, 9);
+    await withClock(Clock(() => now), () async {
+      await relay.check(
+        uuid: 'uuid-1',
+        firmwareVersion: '3.0.0',
+        hardwareCode: 'HW-1',
+      );
+      await relay.download(hardwareCode: 'HW-1', version: '3.1.2');
+      now = now.add(const Duration(hours: 25));
+
+      // Checked again a day on, before any download: fetched anew.
+      await relay.check(
+        uuid: 'uuid-1',
+        firmwareVersion: '3.0.0',
+        hardwareCode: 'HW-1',
+      );
+      await relay.download(hardwareCode: 'HW-1', version: '3.1.2');
+    });
+
+    expect(polar.fetches, 2);
+  });
+}