From b84f0b0b18c2dfe34b25bd73a39c757167524302 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Padez?= <andre.padez@gmail.com>
Date: Mon, 27 Jul 2026 16:07:39 +0000
Subject: [PATCH] =?UTF-8?q?music:=20/manifest=20is=20a=20pure=20read=20?=
 =?UTF-8?q?=E2=80=94=20never=20triggers=20a=20(re)build?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reading the manifest (which every app refresh hits) used to call
ensureIndexFresh(), kicking off a debounced rebuild — and after the CACHE_VERSION
bump that meant a plain refresh could launch a full library rebuild. Make reads
side-effect-free: /manifest now just returns the last completed index. Builds are
explicit only (POST /reindex or the SSE stream); pick up disk changes by
reindexing.

Removes the now-unused ensureIndexFresh + lastBuildFinishedAt, and drops
/manifest from the 30-min per-request timeout extension (both hops) since it no
longer blocks on a build.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/servers/api/music/router.ts      |  2 +-
 src/servers/sidecar/music/index.ts   | 14 ++++++------
 src/servers/sidecar/music/indexer.ts | 32 ++++++----------------------
 3 files changed, 14 insertions(+), 34 deletions(-)

diff --git a/src/servers/api/music/router.ts b/src/servers/api/music/router.ts
index 78d1f356..cced3f7e 100644
--- a/src/servers/api/music/router.ts
+++ b/src/servers/api/music/router.ts
@@ -93,7 +93,7 @@ musicRouter.all('/*', async (ctx) => {
   // A from-scratch reindex holds this proxied connection open for minutes with no bytes flowing, which
   // the main server's 60s idle timeout would drop. Extend it to 30 min for the build/progress endpoints
   // (Bun passes the server as Hono's env). Matches the sidecar's own per-request extension.
-  if (subpath === '/reindex' || subpath === '/manifest' || subpath === '/reindex/stream') {
+  if (subpath === '/reindex' || subpath === '/reindex/stream') {
     const server = ctx.env as { timeout?: (req: Request, seconds: number) => void } | undefined;
     try {
       server?.timeout?.(ctx.req.raw, 1800);
diff --git a/src/servers/sidecar/music/index.ts b/src/servers/sidecar/music/index.ts
index 5f720853..59196b6b 100644
--- a/src/servers/sidecar/music/index.ts
+++ b/src/servers/sidecar/music/index.ts
@@ -5,7 +5,6 @@ import { createSidecarConnector } from '../connect';
 import { streamAudioFile } from './stream-audio';
 import {
   reindexNow,
-  ensureIndexFresh,
   getIndexStatus,
   getManifest,
   albumVersion,
@@ -34,8 +33,8 @@ const DATA_PATH = process.env.DATA_PATH ?? join(process.cwd(), 'data');
 //
 //   GET  /stream?path=<home-relative>      audio with Range→206 (Content-Range/Length/Accept-Ranges)
 //                                          + `X-Audio-Duration` (seconds, ffprobe). 400/404/416.
-//   GET  /manifest                         ensures a fresh index (debounced rebuild) then returns
-//                                          { version, generatedAt, albums: { "<rel>": { v, cover, tracks, disco? } } }
+//   GET  /manifest                         pure read of the last completed index (NO build triggered) —
+//                                          { version, generatedAt, albums: { "<rel>": { v, cover, tracks, videos?, disco? } } }
 //   GET  /meta?path=<rel>                  album meta.json (IndexMeta). ETag: <v>; If-None-Match → 304.
 //   GET  /cover?path=<rel>                 compressed cover.jpg.       ETag: <v>; If-None-Match → 304.
 //   GET  /poster?path=<rel>&file=<video>   compressed video poster (frame grab). ETag: <v>; 304. 404 if none.
@@ -80,8 +79,8 @@ const server = Bun.serve({
   async fetch(req, server) {
     const url = new URL(req.url);
     // A from-scratch reindex can take many minutes with no bytes flowing on the triggering request.
-    // Give the build-triggering + progress endpoints a 30-min idle timeout so they aren't dropped.
-    if (url.pathname === '/reindex' || url.pathname === '/manifest' || url.pathname === '/reindex/stream') {
+    // Give the build endpoints a 30-min idle timeout so they aren't dropped (/manifest is a pure read now).
+    if (url.pathname === '/reindex' || url.pathname === '/reindex/stream') {
       server.timeout(req, 1800);
     }
     const json = (data: unknown, init?: ResponseInit) =>
@@ -157,9 +156,8 @@ const server = Bun.serve({
 
     // ── Sync surface ──
     if (url.pathname === '/manifest') {
-      // Every app refresh funnels through here, so rebuild the index first (debounced) — this is what
-      // makes on-disk changes show up on a plain refresh, not only via the explicit reindex sheet.
-      await ensureIndexFresh();
+      // Pure read — returns the last completed index. It does NOT trigger a build (that could kick off a
+      // long/full rebuild on a plain app refresh); use POST /reindex explicitly to pick up disk changes.
       return json(await getManifest());
     }
 
diff --git a/src/servers/sidecar/music/indexer.ts b/src/servers/sidecar/music/indexer.ts
index 9a2cb440..09ad06ff 100644
--- a/src/servers/sidecar/music/indexer.ts
+++ b/src/servers/sidecar/music/indexer.ts
@@ -499,40 +499,22 @@ export async function buildMusicIndex(): Promise<IndexStatus> {
   return getIndexStatus();
 }
 
-// ── Coalesced / debounced build entry points ──
-// So reads (the manifest fetch that every app refresh funnels through) can ensure freshness without
-// stampeding builds: concurrent callers join one in-flight build, and back-to-back reads within the
-// debounce window skip rebuilding. Route ALL build triggers through reindexNow so there's one tracker.
+// ── Coalesced build entry point ──
+// Builds are EXPLICIT only (POST /reindex, the SSE stream). Reads (/manifest, /meta, /cover, …) never
+// trigger a build — a manifest fetch just returns the last completed index. Route all build triggers
+// through reindexNow so concurrent callers join one in-flight build instead of stampeding.
 
 let inflightBuild: Promise<IndexStatus> | null = null;
-let lastBuildFinishedAt = 0;
 
 /** Run a build, joining an in-flight one instead of starting a second; resolves when it completes. */
 export function reindexNow(): Promise<IndexStatus> {
   if (inflightBuild) return inflightBuild;
-  inflightBuild = buildMusicIndex()
-    .then((s) => {
-      lastBuildFinishedAt = Date.now();
-      return s;
-    })
-    .finally(() => {
-      inflightBuild = null;
-    });
+  inflightBuild = buildMusicIndex().finally(() => {
+    inflightBuild = null;
+  });
   return inflightBuild;
 }
 
-/** Ensure the index reflects recent on-disk changes before a read: await any in-flight build, else
- *  rebuild unless one finished within `debounceMs` (so a refresh that reads the manifest twice in a
- *  row rebuilds once, not twice). */
-export async function ensureIndexFresh(debounceMs = 3000): Promise<void> {
-  if (inflightBuild) {
-    await inflightBuild;
-    return;
-  }
-  if (Date.now() - lastBuildFinishedAt < debounceMs) return;
-  await reindexNow();
-}
-
 async function walk(dirAbs: string, prev: Manifest, next: Manifest): Promise<void> {
   status.currentPath = relative(MUSIC_ROOT, dirAbs) || '.';
   status.foldersScanned += 1;