fix: radar false crashes, wrong sides, and a pole side per track

package.json

@@ -46,6 +46,7 @@
     "fetch-lovely-data": "npx tsx ./tools/fetch-lovely-data.ts",
     "fetch-lovely-track-data": "npx tsx ./tools/fetch-lovely-track-data.ts",
     "generate-garage61-ids": "npx tsx ./tools/generate-garage61-ids.ts",
+    "generate-radar-pole-sides": "npx tsx ./tools/generate-radar-pole-sides.ts",
     "prepare": "husky"
   },
   "devDependencies": {

src/app/analytics.radarPoleSide.spec.ts

@@ -0,0 +1,199 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { EventMessage, IdentifyMessage } from 'posthog-node';
+import type { DashboardLayout } from '@irdashies/types';
+import os from 'node:os';
+import path from 'node:path';
+import { mkdtempSync } from 'node:fs';
+
+const { userDataPath, store } = vi.hoisted(() => ({
+  userDataPath: { value: '' },
+  store: { data: new Map<string, unknown>() },
+}));
+
+vi.mock('electron', () => ({
+  app: { getPath: vi.fn(() => userDataPath.value) },
+  screen: {
+    getAllDisplays: vi.fn().mockReturnValue([]),
+    getPrimaryDisplay: vi
+      .fn()
+      .mockReturnValue({ size: { width: 0, height: 0 } }),
+  },
+}));
+
+vi.mock('electron-log/main', () => ({
+  default: {
+    transports: { file: {}, console: {} },
+    initialize: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  },
+}));
+
+vi.mock('./storage/storage', () => ({
+  readData: vi.fn((key: string) => store.data.get(key)),
+  writeData: vi.fn((key: string, value: unknown) => store.data.set(key, value)),
+}));
+
+vi.mock('./storage/analytics', () => ({
+  getAnalyticsOptOut: vi.fn().mockReturnValue(false),
+}));
+
+const { corrections, flipped } = vi.hoisted(() => ({
+  corrections: { value: {} as Record<string, unknown> },
+  flipped: { listeners: new Set<() => void>() },
+}));
+vi.mock('./storage/radarPoleSideOverrides', () => ({
+  radarPoleSideOverrides: {
+    snapshot: () => corrections.value,
+    onChange: (listener: () => void) => {
+      flipped.listeners.add(listener);
+      return () => flipped.listeners.delete(listener);
+    },
+  },
+}));
+
+import { Analytics } from './analytics';
+import { getAnalyticsOptOut } from './storage/analytics';
+
+const HASH_KEY = 'radarPoleSideReportHash';
+
+const makeProvider = () => ({
+  capture: vi.fn<(event: EventMessage) => void>(),
+  captureConfirmed: vi
+    .fn<(event: EventMessage) => Promise<void>>()
+    .mockResolvedValue(undefined),
+  identify: vi.fn<(message: IdentifyMessage) => void>(),
+  shutdown: vi.fn<(shutdownTimeoutMs?: number) => void>(),
+});
+
+describe('Analytics radar pole side report', () => {
+  let provider: ReturnType<typeof makeProvider>;
+
+  const start = async (version = '2.0.0') => {
+    const analytics = new Analytics(provider);
+    await analytics.init(version, {} as DashboardLayout);
+    await analytics.waitForRadarPoleSideUpload();
+  };
+  const reports = () =>
+    provider.captureConfirmed.mock.calls
+      .map(([event]) => event)
+      .filter((event) => event.event === 'radar_pole_side');
+
+  beforeEach(() => {
+    userDataPath.value = mkdtempSync(path.join(os.tmpdir(), 'irdashies-'));
+    store.data.clear();
+    corrections.value = {};
+    flipped.listeners.clear();
+    provider = makeProvider();
+    vi.mocked(getAnalyticsOptOut).mockReturnValue(false);
+  });
+
+  it('sends nothing for an installation that never corrected a side', async () => {
+    await start();
+    expect(reports()).toEqual([]);
+  });
+
+  it('reports the corrections once, then remembers what was acknowledged', async () => {
+    corrections.value = { '95': { start: false, table: true } };
+    await start();
+
+    expect(reports()).toHaveLength(1);
+    expect(reports()[0]).toMatchObject({
+      event: 'radar_pole_side',
+      properties: {
+        version: '2.0.0',
+        track_count: 1,
+        tracks: { '95': { start_left: false, table_left: true } },
+      },
+    });
+    expect(store.data.get(HASH_KEY)).toBe(reports()[0].properties?.data_hash);
+
+    await start('3.0.0');
+    expect(reports()).toHaveLength(1);
+  });
+
+  it('reports a change, and a revert to nothing', async () => {
+    corrections.value = { '95': { start: false, table: true } };
+    await start();
+    corrections.value = {
+      '95': { start: false, restart: false, table: true },
+    };
+    await start();
+    corrections.value = {};
+    await start();
+
+    expect(reports()).toHaveLength(3);
+    expect(reports()[2].properties?.track_count).toBe(0);
+  });
+
+  it('does not record a hash when delivery fails, so it is retried', async () => {
+    corrections.value = { '95': { start: false, table: true } };
+    provider.captureConfirmed.mockRejectedValueOnce(new Error('down'));
+    await expect(start()).resolves.toBeUndefined();
+    expect(store.data.get(HASH_KEY)).toBeUndefined();
+
+    await start();
+    expect(store.data.get(HASH_KEY)).toBeDefined();
+  });
+
+  it('respects the analytics opt-out', async () => {
+    corrections.value = { '95': { start: false, table: true } };
+    vi.mocked(getAnalyticsOptOut).mockReturnValue(true);
+    await start();
+    expect(reports()).toEqual([]);
+  });
+
+  it('ignores a stored value that is not a hash', async () => {
+    store.data.set(HASH_KEY, 'not-a-hash');
+    await start();
+    expect(reports()).toEqual([]);
+  });
+
+  describe('after a flip', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    const flip = () => flipped.listeners.forEach((listener) => listener());
+
+    it('reports a minute after the last flip, not at once and not once per press', async () => {
+      await start();
+      expect(reports()).toEqual([]);
+
+      corrections.value = { '95': { start: false, table: true } };
+      flip();
+      await vi.advanceTimersByTimeAsync(30_000);
+      flip();
+      await vi.advanceTimersByTimeAsync(59_000);
+      expect(reports()).toEqual([]);
+
+      await vi.advanceTimersByTimeAsync(2_000);
+      expect(reports()).toHaveLength(1);
+      expect(reports()[0].properties?.track_count).toBe(1);
+      expect(store.data.get(HASH_KEY)).toBeDefined();
+    });
+
+    it('sends nothing when the flips cancelled out and nothing was ever sent', async () => {
+      await start();
+      flip();
+      await vi.advanceTimersByTimeAsync(61_000);
+      expect(reports()).toEqual([]);
+    });
+
+    it('stops its timer when the app shuts down', async () => {
+      const analytics = new Analytics(provider);
+      await analytics.init('2.0.0', {} as DashboardLayout);
+      await analytics.waitForRadarPoleSideUpload();
+      corrections.value = { '95': { start: false, table: true } };
+      flip();
+      analytics.shutdown();
+      await vi.advanceTimersByTimeAsync(120_000);
+      expect(reports()).toEqual([]);
+    });
+  });
+});

src/app/analytics.ts

@@ -10,13 +10,27 @@ import logger from './logger';
 import type ElectronLog from 'electron-log';
 import type { LogMessage } from 'electron-log';
 import { readPitLaneCalibrationForAnalytics } from './analytics/pitLaneCalibration';
+import {
+  MAX_POLE_SIDE_PROPERTIES_BYTES,
+  buildRadarPoleSideReport,
+} from './analytics/radarPoleSideReport';
+import { radarPoleSideOverrides } from './storage/radarPoleSideOverrides';
 import {
   readPitLaneAnalyticsCheckpoint,
   writePitLaneAnalyticsCheckpoint,
 } from './storage/pitLaneAnalyticsCheckpoint';
 
 declare const POSTHOG_KEY: string;
 
+/**
+ * How long after the last flip the radar pole side report goes out, so a
+ * burst of key presses is one report and nothing waits for the next launch.
+ */
+const POLE_SIDE_REPORT_DELAY_MS = 60 * 1000;
+
+/** Hash of the last radar pole side report PostHog acknowledged. */
+const POLE_SIDE_HASH_KEY = 'radarPoleSideReportHash';
+
 const DEDUP_WINDOW_MS = 60 * 60 * 1000;
 const DEDUP_KEY_LENGTH = 30;
 const DEDUP_MAX_ENTRIES = 5000;
@@ -80,6 +94,10 @@ export class Analytics {
   private provider: AnalyticsProvider | null = null;
   private pitLaneCalibrationAttempted = false;
   private pitLaneCalibrationTask: Promise<void> | undefined;
+  private radarPoleSideTask: Promise<void> | undefined;
+  private poleSideEvent: { hash: string; uuid: string } | undefined;
+  private radarPoleSideTimer: ReturnType<typeof setTimeout> | undefined;
+  private watchingRadarPoleSides = false;
 
   constructor(provider?: AnalyticsProvider) {
     if (provider) {
@@ -122,6 +140,7 @@ export class Analytics {
   }
 
   shutdown(shutdownTimeoutMs?: number): void {
+    clearTimeout(this.radarPoleSideTimer);
     if (this.provider) {
       this.provider.shutdown(shutdownTimeoutMs);
     }
@@ -214,6 +233,84 @@ export class Analytics {
     ).catch(() => {
       logger.warn('[Analytics] Could not publish pit lane calibration');
     });
+    // After the pit lane report, so startup does one thing at a time.
+    this.radarPoleSideTask ??= this.pitLaneCalibrationTask.then(() =>
+      this.captureRadarPoleSides(userId, version)
+    );
+    this.reportRadarPoleSidesAfterFlips(userId, version);
+  }
+
+  /**
+   * A flip is reported a minute after the last one rather than at the next
+   * launch. If the app closes first, the launch still sends it, since the
+   * acknowledged hash was never recorded.
+   */
+  private reportRadarPoleSidesAfterFlips(
+    userId: string,
+    version: string
+  ): void {
+    if (this.watchingRadarPoleSides) return;
+    this.watchingRadarPoleSides = true;
+    radarPoleSideOverrides.onChange(() => {
+      clearTimeout(this.radarPoleSideTimer);
+      this.radarPoleSideTimer = setTimeout(() => {
+        this.radarPoleSideTask = (
+          this.radarPoleSideTask ?? Promise.resolve()
+        ).then(() => this.captureRadarPoleSides(userId, version));
+      }, POLE_SIDE_REPORT_DELAY_MS);
+      this.radarPoleSideTimer.unref?.();
+    });
+  }
+
+  waitForRadarPoleSideUpload(): Promise<void> {
+    return this.radarPoleSideTask ?? Promise.resolve();
+  }
+
+  /**
+   * Reports the pole sides the player corrected with the radar key, once per
+   * change, in the background. A revert to the table is reported too, but
+   * nothing is sent for an installation that never corrected anything.
+   */
+  private async captureRadarPoleSides(
+    userId: string,
+    version: string
+  ): Promise<void> {
+    try {
+      if (!this.provider || getAnalyticsOptOut()) return;
+      const report = buildRadarPoleSideReport(
+        radarPoleSideOverrides.snapshot(),
+        version
+      );
+      const stored = readData<unknown>(POLE_SIDE_HASH_KEY);
+      const last =
+        typeof stored === 'string' && /^[0-9a-f]{64}$/.test(stored)
+          ? stored
+          : undefined;
+      if (report.properties.track_count === 0 && last === undefined) return;
+      if (last === report.hash) return;
+      if (
+        Buffer.byteLength(JSON.stringify(report.properties), 'utf8') >
+        MAX_POLE_SIDE_PROPERTIES_BYTES
+      ) {
+        logger.warn('[Analytics] Skipping oversized radar pole side report');
+        return;
+      }
+      // The same report keeps its event id across retries, so a send whose
+      // acknowledgement was lost is not counted twice while the app runs.
+      if (this.poleSideEvent?.hash !== report.hash) {
+        this.poleSideEvent = { hash: report.hash, uuid: crypto.randomUUID() };
+      }
+      await this.provider.captureConfirmed({
+        distinctId: userId,
+        event: 'radar_pole_side',
+        uuid: this.poleSideEvent.uuid,
+        properties: report.properties,
+      });
+      // Recorded only after PostHog acknowledged it, so a failure retries.
+      if (!getAnalyticsOptOut()) writeData(POLE_SIDE_HASH_KEY, report.hash);
+    } catch {
+      logger.warn('[Analytics] Could not publish radar pole side report');
+    }
   }
 
   waitForCalibrationUpload(): Promise<void> {