feat(library): warm rotation-tracks picker LRU on backend boot (#998)

apps/backend/app.ts

@@ -22,8 +22,9 @@
 import { startPlaylistProxy, stopPlaylistProxy } from './services/playlist-proxy.service.js';
 import { startAlbumPlaysRefresh, stopAlbumPlaysRefresh } from './services/album-plays-refresh.service.js';
 import { setupCdcWebSocket, shutdownCdcWebSocket } from './services/cdc/index.js';
+import { startRotationTracksCacheWarm } from './services/rotation-tracks-cache-warm.service.js';
 import { drainInFlightEnrichments } from './services/metadata/enrichment.service.js';
 import { activeShow } from './middleware/checkActiveShow.js';
 import errorHandler from './middleware/errorHandler.js';
 import { shouldCaptureExpressError } from './middleware/sentryErrorFilter.js';
 import { requestIdMiddleware } from './middleware/requestId.js';
@@ -63,8 +64,8 @@
 );
 
 // Serve documentation
 const swaggerDoc = parse_yaml(swaggerContent);
 app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDoc));
 
 // Public configuration endpoint (unauthenticated)
 app.use('/config', config_route);
@@ -100,7 +101,7 @@
 );
 
 //example for how to use te Cognito auth middleware
 app.get('/testAuth', requirePermissions({ flowsheet: ['read'] }), async (req, res) => {
   res.json({ message: 'Authenticated!' });
 });
 
@@ -132,6 +133,12 @@
   startPlaylistProxy();
   startAlbumPlaysRefresh();
   void setupCdcWebSocket(server);
+  // One-shot warm of the rotation-tracks picker LRUs in
+  // `library.service.ts`. Fire-and-forget — the walk shares the LML
+  // semaphore with concurrent traffic, and the LRUs are process-local so
+  // the work would otherwise have to happen on the first picker open per
+  // row after every restart. See `services/rotation-tracks-cache-warm.service.ts`.
+  startRotationTracksCacheWarm();
 });
 
 // Strictly greater than the LML client's 30 s AbortController

apps/backend/services/library.service.ts

@@ -370,6 +370,20 @@ export function __resetRotationLmlLookupCacheForTests(): void {
   rotationLmlNegativeCache.clear();
 }
 
+/**
+ * Current sizes of the rotation LML LRUs. Used by the rotation-tracks
+ * cache-warm service (BS#998) to classify warm-pass outcomes per row
+ * (positive-cache-hit vs negative-cache-hit) without coupling to LRU
+ * internals. Underscored so it stays out of the public service surface —
+ * production callers should not depend on cache shape.
+ */
+export function __rotationLmlCacheSizesForWarm(): { positive: number; negative: number } {
+  return {
+    positive: rotationLmlPositiveCache.size,
+    negative: rotationLmlNegativeCache.size,
+  };
+}
+
 /**
  * Look up the resolved Discogs release id for a rotation row by its id.
  *

apps/backend/services/rotation-tracks-cache-warm.service.ts

@@ -0,0 +1,177 @@
+/**
+ * One-shot warm pass for the rotation-tracks picker LRU caches in
+ * `library.service.ts` (BS#987's `rotationLmlPositiveCache` +
+ * `rotationLmlNegativeCache`).
+ *
+ * Why this lives in the API process and not in a `jobs/` package:
+ *   The LRUs are process-local (`new LRUCache(...)` at module scope), so a
+ *   sidecar one-shot job would warm its own copy and exit — useless for the
+ *   long-lived API process that serves `GET /library/rotation/:id/tracks`.
+ *   Tubafrenzy's `RotationTracklistCache.warmCache` does the equivalent on
+ *   JVM boot.
+ *
+ * What gets warmed:
+ *   For every active rotation row (`kill_date IS NULL OR kill_date >
+ *   CURRENT_DATE` — the same predicate `getRotationFromDB` uses), the warmer
+ *   calls `getDiscogsReleaseIdByRotationId` end-to-end so it goes through
+ *   the same three-tier resolver real picker opens take. That means the
+ *   warm walk shares the LML chokepoint with concurrent user traffic —
+ *   `lookupSemaphore` (5 permits) and the rate-limit token bucket throttle
+ *   it naturally, and the per-call 5 s budget from #993 caps tail latency.
+ *   Rows resolved via tier 1 or tier 2 (DB lookup, no LML call) cost ~1 ms;
+ *   rows that fall through to tier 3 spend a semaphore permit but populate
+ *   either the positive or the negative LRU so the next picker open is
+ *   instant.
+ *
+ * Fire-and-forget on app boot:
+ *   We don't await the warm before `app.listen` resolves — health checks
+ *   and live traffic should not pay startup latency for a best-effort
+ *   optimization. A single row's failure is captured to Sentry and logged
+ *   but does not stop the walk; the warm just continues with the next id.
+ *   On process restart, the warmer re-runs (the LRU is in RAM); ~310 rows
+ *   × ~few-second tail per LML call ≈ a few minutes of background traffic
+ *   per restart, which is acceptable on a process that runs for days.
+ *
+ * Exported API:
+ *   warmRotationTracksCache() — perform a single walk and return the
+ *                               counters (used by `start...` and tests).
+ *   startRotationTracksCacheWarm() — fire-and-forget kickoff; called once
+ *                                   from `app.ts` post-`listen`.
+ */
+import * as Sentry from '@sentry/node';
+import { sql } from 'drizzle-orm';
+import { db, rotation } from '@wxyc/database';
+import { getDiscogsReleaseIdByRotationId, __rotationLmlCacheSizesForWarm } from './library.service.js';
+
+const LOG_PREFIX = '[rotation-tracks-cache-warm]';
+
+/**
+ * Log progress every N rows. 50 keeps the boot log readable for the prod
+ * row count (~310) — about six progress lines plus a final summary.
+ */
+const PROGRESS_LOG_EVERY = 50;
+
+export interface WarmCounters {
+  /** Total rows walked. */
+  scanned: number;
+  /** Rows that resolved via tier 1 or 2 (no LML call). */
+  preResolved: number;
+  /** Rows that hit LML and got a release id (positive cache populated). */
+  lmlPositive: number;
+  /** Rows that hit LML and got nothing (negative cache populated). */
+  lmlNegative: number;
+  /** Rows where `getDiscogsReleaseIdByRotationId` threw. */
+  errors: number;
+  /** Wall-clock duration of the walk in ms. */
+  elapsedMs: number;
+}
+
+/**
+ * Walk every active rotation row, calling `getDiscogsReleaseIdByRotationId`
+ * for each so the per-`rotation_id` LRUs in `library.service.ts` are populated.
+ *
+ * Sequential by design — `getDiscogsReleaseIdByRotationId` itself acquires
+ * the `lookupSemaphore` permit when it falls through to LML, so the upper
+ * bound on outstanding LML calls remains 5. Driving extra concurrency here
+ * would only deepen the semaphore queue without raising throughput, while
+ * stealing fairness from concurrent user requests.
+ *
+ * The before/after delta of the positive + negative LRU sizes (read via the
+ * test-only sizes accessor) reconstructs the LML-positive vs LML-negative
+ * tally without coupling this service to the LRU internals or requiring a
+ * second pass.
+ */
+export async function warmRotationTracksCache(): Promise<WarmCounters> {
+  const startTime = Date.now();
+  const startSizes = __rotationLmlCacheSizesForWarm();
+
+  const rows = await db
+    .select({ id: rotation.id })
+    .from(rotation)
+    .where(sql`${rotation.kill_date} > CURRENT_DATE OR ${rotation.kill_date} IS NULL`);
+
+  const counters: WarmCounters = {
+    scanned: 0,
+    preResolved: 0,
+    lmlPositive: 0,
+    lmlNegative: 0,
+    errors: 0,
+    elapsedMs: 0,
+  };
+
+  console.log(`${LOG_PREFIX} starting walk over ${rows.length} active rotation row(s)`);
+
+  for (const row of rows) {
+    const rotationId = row.id as unknown as number;
+    counters.scanned += 1;
+
+    try {
+      const beforeSizes = __rotationLmlCacheSizesForWarm();
+      const result = await getDiscogsReleaseIdByRotationId(rotationId);
+      const afterSizes = __rotationLmlCacheSizesForWarm();
+
+      // Per-row LRU-delta classifier: if a positive entry was added during
+      // this iteration the row was a fresh tier-3 hit; same for negative.
+      // No size change means the row resolved via tier 1 or tier 2 (or hit
+      // a previously-cached LML result, which only happens on a duplicate
+      // rotation_id — impossible from this query but cheap to handle as
+      // "pre-resolved" since we did no LML work).
+      if (afterSizes.positive > beforeSizes.positive) {
+        counters.lmlPositive += 1;
+      } else if (afterSizes.negative > beforeSizes.negative) {
+        counters.lmlNegative += 1;
+      } else if (result !== null) {
+        counters.preResolved += 1;
+      } else {
+        // Null with no LRU growth: tier 1+2 missed and LML was either
+        // unconfigured, returned the same negative we'd already cached, or
+        // declined the row due to NULL artist_name/album_title. None of
+        // these populate either LRU, so we fold them into preResolved for
+        // the summary (the picker won't pay an LML round-trip on next open
+        // either way — it'll degrade to free-text immediately).
+        counters.preResolved += 1;
+      }
+    } catch (err) {
+      counters.errors += 1;
+      Sentry.captureException(err, {
+        tags: { subsystem: 'rotation-tracks-cache-warm' },
+        extra: { rotation_id: rotationId },
+      });
+      console.warn(`${LOG_PREFIX} row ${rotationId} failed: ${(err as Error).message}`);
+    }
+
+    if (counters.scanned % PROGRESS_LOG_EVERY === 0) {
+      console.log(
+        `${LOG_PREFIX} progress: scanned=${counters.scanned}/${rows.length} ` +
+          `preResolved=${counters.preResolved} lmlPositive=${counters.lmlPositive} ` +
+          `lmlNegative=${counters.lmlNegative} errors=${counters.errors}`
+      );
+    }
+  }
+
+  counters.elapsedMs = Date.now() - startTime;
+
+  console.log(
+    `${LOG_PREFIX} done: scanned=${counters.scanned} preResolved=${counters.preResolved} ` +
+      `lmlPositive=${counters.lmlPositive} lmlNegative=${counters.lmlNegative} ` +
+      `errors=${counters.errors} elapsedMs=${counters.elapsedMs} ` +
+      `(starting cache sizes positive=${startSizes.positive} negative=${startSizes.negative})`
+  );
+
+  return counters;
+}
+
+/**
+ * Fire-and-forget kickoff for app boot. Returns immediately; the walk runs
+ * in the background. A top-level walk failure (DB outage, for instance) is
+ * captured to Sentry and logged — boot should not depend on the walk
+ * succeeding.
+ */
+export function startRotationTracksCacheWarm(): void {
+  void warmRotationTracksCache().catch((err) => {
+    Sentry.captureException(err, {
+      tags: { subsystem: 'rotation-tracks-cache-warm' },
+    });
+    console.error(`${LOG_PREFIX} walk aborted:`, err);
+  });
+}