Harden listening endpoint runtime error handling

README.md

@@ -71,12 +71,14 @@
 ## Listening tokens
 
 - Funkwhale endpoint requirements:
-- `FUNKWHALE_INSTANCE` (for example `https://your-funkwhale.example`)
+- `FUNKWHALE_INSTANCE` (for example `https://your-funkwhale.example`, root server URL only)
 - `FUNKWHALE_USERNAME`
 - `FUNKWHALE_TOKEN` (read API token)
 - Last.fm endpoint requirements:
 - `LASTFM_API_KEY`
 - `LASTFM_USERNAME`
+- Listening endpoint plugins target Node.js 20+; older runtimes can produce inconsistent fetch/JSON behavior.
+- If `FUNKWHALE_INSTANCE` points to a host that does not expose Funkwhale's API routes, API responses now degrade to empty data instead of repeated 500 errors.
 - If these variables are missing, the endpoints still exist but return empty activity until credentials are configured.
 
 ## ActivityPub
@@ -101,7 +103,7 @@
 - `start.sh` is intentionally ignored by Git (`.gitignore`) so server secrets are not committed.
 - Use `start.example.sh` as the tracked template and keep real credentials in environment variables (or `.env` on the server).
 - Startup scripts parse `.env` with the `dotenv` parser (not shell `source`), so values containing spaces are handled safely.
-- Startup scripts run preflight + patch helpers before boot (`scripts/preflight-production-security.mjs`, `scripts/preflight-mongo-connection.mjs`, `scripts/patch-lightningcss.mjs`, `scripts/patch-endpoint-media-scope.mjs`, `scripts/patch-endpoint-media-sharp-runtime.mjs`, `scripts/patch-frontend-sharp-runtime.mjs`, `scripts/patch-endpoint-files-upload-route.mjs`, `scripts/patch-endpoint-files-upload-locales.mjs`, `scripts/patch-frontend-serviceworker-file.mjs`, `scripts/patch-conversations-collection-guards.mjs`, `scripts/patch-indiekit-routes-rate-limits.mjs`, `scripts/patch-indiekit-error-production-stack.mjs`, `scripts/patch-indieauth-devmode-guard.mjs`).
+- Startup scripts run preflight + patch helpers before boot (`scripts/preflight-production-security.mjs`, `scripts/preflight-mongo-connection.mjs`, `scripts/patch-lightningcss.mjs`, `scripts/patch-endpoint-media-scope.mjs`, `scripts/patch-endpoint-media-sharp-runtime.mjs`, `scripts/patch-frontend-sharp-runtime.mjs`, `scripts/patch-endpoint-files-upload-route.mjs`, `scripts/patch-endpoint-files-upload-locales.mjs`, `scripts/patch-frontend-serviceworker-file.mjs`, `scripts/patch-conversations-collection-guards.mjs`, `scripts/patch-indiekit-routes-rate-limits.mjs`, `scripts/patch-indiekit-error-production-stack.mjs`, `scripts/patch-indieauth-devmode-guard.mjs`, `scripts/patch-listening-endpoint-runtime-guards.mjs`).
 - The production security preflight blocks startup on insecure auth/session configuration and catches empty-password bcrypt hashes.
 - One-time recovery mode is available with `INDIEKIT_ALLOW_PASSWORD_SETUP=1` to bootstrap/reset `PASSWORD_SECRET` when locked out. Remove this flag after setting a valid hash.
 - The media scope patch fixes a known upstream issue where file uploads can fail if the token scope is `create update delete` without explicit `media`.

package.json

@@ -4,8 +4,8 @@
   "description": "",
   "main": "index.js",
   "scripts": {
-    "postinstall": "node scripts/patch-lightningcss.mjs && node scripts/patch-endpoint-media-scope.mjs && node scripts/patch-endpoint-media-sharp-runtime.mjs && node scripts/patch-frontend-sharp-runtime.mjs && node scripts/patch-endpoint-files-upload-route.mjs && node scripts/patch-endpoint-files-upload-locales.mjs && node scripts/patch-frontend-serviceworker-file.mjs && node scripts/patch-conversations-collection-guards.mjs && node scripts/patch-indiekit-routes-rate-limits.mjs && node scripts/patch-indiekit-error-production-stack.mjs && node scripts/patch-indieauth-devmode-guard.mjs",
+    "postinstall": "node scripts/patch-lightningcss.mjs && node scripts/patch-endpoint-media-scope.mjs && node scripts/patch-endpoint-media-sharp-runtime.mjs && node scripts/patch-frontend-sharp-runtime.mjs && node scripts/patch-endpoint-files-upload-route.mjs && node scripts/patch-endpoint-files-upload-locales.mjs && node scripts/patch-frontend-serviceworker-file.mjs && node scripts/patch-conversations-collection-guards.mjs && node scripts/patch-indiekit-routes-rate-limits.mjs && node scripts/patch-indiekit-error-production-stack.mjs && node scripts/patch-indieauth-devmode-guard.mjs && node scripts/patch-listening-endpoint-runtime-guards.mjs",
-    "serve": "export NODE_ENV=${NODE_ENV:-production} INDIEKIT_DEBUG=${INDIEKIT_DEBUG:-0} && node scripts/preflight-production-security.mjs && node scripts/preflight-mongo-connection.mjs && node scripts/patch-lightningcss.mjs && node scripts/patch-endpoint-media-scope.mjs && node scripts/patch-endpoint-media-sharp-runtime.mjs && node scripts/patch-frontend-sharp-runtime.mjs && node scripts/patch-endpoint-files-upload-route.mjs && node scripts/patch-endpoint-files-upload-locales.mjs && node scripts/patch-frontend-serviceworker-file.mjs && node scripts/patch-conversations-collection-guards.mjs && node scripts/patch-indiekit-routes-rate-limits.mjs && node scripts/patch-indiekit-error-production-stack.mjs && node scripts/patch-indieauth-devmode-guard.mjs && node node_modules/@indiekit/indiekit/bin/cli.js serve --config indiekit.config.mjs",
+    "serve": "export NODE_ENV=${NODE_ENV:-production} INDIEKIT_DEBUG=${INDIEKIT_DEBUG:-0} && node scripts/preflight-production-security.mjs && node scripts/preflight-mongo-connection.mjs && node scripts/patch-lightningcss.mjs && node scripts/patch-endpoint-media-scope.mjs && node scripts/patch-endpoint-media-sharp-runtime.mjs && node scripts/patch-frontend-sharp-runtime.mjs && node scripts/patch-endpoint-files-upload-route.mjs && node scripts/patch-endpoint-files-upload-locales.mjs && node scripts/patch-frontend-serviceworker-file.mjs && node scripts/patch-conversations-collection-guards.mjs && node scripts/patch-indiekit-routes-rate-limits.mjs && node scripts/patch-indiekit-error-production-stack.mjs && node scripts/patch-indieauth-devmode-guard.mjs && node scripts/patch-listening-endpoint-runtime-guards.mjs && node node_modules/@indiekit/indiekit/bin/cli.js serve --config indiekit.config.mjs",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "keywords": [],

scripts/patch-listening-endpoint-runtime-guards.mjs

@@ -0,0 +1,157 @@
+import { access, readFile, writeFile } from "node:fs/promises";
+
+const patchSpecs = [
+  {
+    name: "lastfm-invalid-json-guard",
+    marker: "Invalid JSON response preview",
+    oldSnippet: "    const data = await response.json();",
+    newSnippet: `    const rawBody = await response.text();
+    let data;
+    try {
+      data = JSON.parse(rawBody);
+    } catch {
+      const preview = rawBody.slice(0, 200).replace(/\\s+/g, " ").trim();
+      console.error("[Last.fm] Invalid JSON response preview:", preview);
+      throw new Error("Last.fm API returned invalid JSON");
+    }`,
+    candidates: [
+      "node_modules/@rmdes/indiekit-endpoint-lastfm/lib/lastfm-client.js",
+      "node_modules/@indiekit/indiekit/node_modules/@rmdes/indiekit-endpoint-lastfm/lib/lastfm-client.js",
+    ],
+  },
+  {
+    name: "funkwhale-sync-not-found-guard",
+    marker: "Remote API endpoint not found; skipping sync",
+    oldSnippet: `  const result = await syncListenings(db, client);
+
+  // Update stats cache after sync`,
+    newSnippet: `  let result;
+  try {
+    result = await syncListenings(db, client);
+  } catch (err) {
+    const status = Number(err?.status || err?.statusCode || 0);
+    const message = String(err?.message || "");
+    if (status === 404 || /not found/i.test(message)) {
+      console.warn(
+        "[Funkwhale] Remote API endpoint not found; skipping sync. Check FUNKWHALE_INSTANCE points to your Funkwhale server root URL."
+      );
+      return { synced: 0, error: "Not Found" };
+    }
+    throw err;
+  }
+
+  // Update stats cache after sync`,
+    candidates: [
+      "node_modules/@rmdes/indiekit-endpoint-funkwhale/lib/sync.js",
+      "node_modules/@indiekit/indiekit/node_modules/@rmdes/indiekit-endpoint-funkwhale/lib/sync.js",
+    ],
+  },
+  {
+    name: "funkwhale-now-playing-fallback",
+    marker: "degrade to empty now-playing response when upstream endpoint is missing",
+    oldSnippet: `    } catch (error) {
+      console.error("[Funkwhale] Now Playing API error:", error);
+      response.status(500).json({ error: error.message });
+    }`,
+    newSnippet: `    } catch (error) {
+      const message = String(error?.message || "");
+      // degrade to empty now-playing response when upstream endpoint is missing
+      if (/not found/i.test(message)) {
+        return response.json({
+          playing: false,
+          status: null,
+          message: "No recent plays",
+        });
+      }
+
+      console.error("[Funkwhale] Now Playing API error:", error);
+      response.status(500).json({ error: message || "Unknown error" });
+    }`,
+    candidates: [
+      "node_modules/@rmdes/indiekit-endpoint-funkwhale/lib/controllers/now-playing.js",
+      "node_modules/@indiekit/indiekit/node_modules/@rmdes/indiekit-endpoint-funkwhale/lib/controllers/now-playing.js",
+    ],
+  },
+  {
+    name: "funkwhale-listenings-fallback",
+    marker: "degrade to empty listening history when upstream endpoint is missing",
+    oldSnippet: `    } catch (error) {
+      console.error("[Funkwhale] Listenings API error:", error);
+      response.status(500).json({ error: error.message });
+    }`,
+    newSnippet: `    } catch (error) {
+      const message = String(error?.message || "");
+      // degrade to empty listening history when upstream endpoint is missing
+      if (/not found/i.test(message)) {
+        const fallbackPage = Number.parseInt(request.query.page, 10) || 1;
+        return response.json({
+          listenings: [],
+          total: 0,
+          page: fallbackPage,
+          hasNext: false,
+          hasPrev: false,
+        });
+      }
+
+      console.error("[Funkwhale] Listenings API error:", error);
+      response.status(500).json({ error: message || "Unknown error" });
+    }`,
+    candidates: [
+      "node_modules/@rmdes/indiekit-endpoint-funkwhale/lib/controllers/listenings.js",
+      "node_modules/@indiekit/indiekit/node_modules/@rmdes/indiekit-endpoint-funkwhale/lib/controllers/listenings.js",
+    ],
+  },
+];
+
+async function exists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+let filesChecked = 0;
+let filesPatched = 0;
+
+for (const spec of patchSpecs) {
+  let foundAnyTarget = false;
+
+  for (const filePath of spec.candidates) {
+    if (!(await exists(filePath))) {
+      continue;
+    }
+
+    foundAnyTarget = true;
+    filesChecked += 1;
+
+    const source = await readFile(filePath, "utf8");
+
+    if (source.includes(spec.marker)) {
+      continue;
+    }
+
+    if (!source.includes(spec.oldSnippet)) {
+      continue;
+    }
+
+    const updated = source.replace(spec.oldSnippet, spec.newSnippet);
+    await writeFile(filePath, updated, "utf8");
+    filesPatched += 1;
+  }
+
+  if (!foundAnyTarget) {
+    console.log(`[postinstall] ${spec.name}: no target files found`);
+  }
+}
+
+if (filesChecked === 0) {
+  console.log("[postinstall] No listening endpoint files found");
+} else if (filesPatched === 0) {
+  console.log("[postinstall] listening endpoint runtime guards already patched");
+} else {
+  console.log(
+    `[postinstall] Patched listening endpoint runtime guards in ${filesPatched}/${filesChecked} file(s)`,
+  );
+}

start.example.sh

@@ -57,5 +57,6 @@ unset DEBUG
 /usr/local/bin/node scripts/patch-indiekit-routes-rate-limits.mjs
 /usr/local/bin/node scripts/patch-indiekit-error-production-stack.mjs
 /usr/local/bin/node scripts/patch-indieauth-devmode-guard.mjs
+/usr/local/bin/node scripts/patch-listening-endpoint-runtime-guards.mjs
 
 exec /usr/local/bin/node node_modules/@indiekit/indiekit/bin/cli.js serve --config indiekit.config.mjs