From 5fff6d67b08b4fa6df1586152b47506a146e18a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andrew=20Beveridge=20=E2=98=84=EF=B8=8F?= Date: Sat, 22 Aug 2026 18:35:12 -0400 Subject: [PATCH] =?UTF-8?q?fix(fallbacks):=20T1=20=E2=80=94=20flacfetch=20?= =?UTF-8?q?sole=20downloader,=20no=20silent=20YouTube=20downgrade=20(#806)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Theme 1 of the silent-fallback audit (`docs/archive/2026-06-09-fallback-audit-plan.md`, added in #805). flacfetch is the sole/lossless downloader — a configured-remote failure must not silently downgrade to a local YouTube-only rip. This is the exact class as the 2026-06-08 Facebook-URL incident. ## Changes - **`audio_search_service._search_remote`**: a `FlacfetchServiceError` from the remote service was swallowed and silently re-run against the local YouTube-only fetcher. Now fails loudly (`AudioSearchError`) and clears cached state. **No silent downgrade.** - **`create_audio_fetcher`** (local CLI factory): a half-configured remote (exactly one of `FLACFETCH_API_URL`/`FLACFETCH_API_KEY`) used to warn and silently use local mode, masking a deploy/secret typo. Now raises `AudioFetcherError`. ## Scope / deferred (needs your call) Findings **1.2** (tracker configured-but-unusable → silently YouTube-only) and **1.4** (`select_best` → first result on ranking failure) live in the **shared local `FlacFetcher`** and have dedicated tests asserting graceful local-CLI behaviour (`test_select_best_handles_exception`). Your "fail loud" directive was framed around the *cloud* silent-downgrade; hard-failing the local CLI when a user simply has no usable tracker would change intentional local behaviour. **Deferred for a per-item decision** rather than steamrolled — see the audit plan doc. ## Testing - [x] `backend/tests/test_audio_search.py` + `tests/unit/test_audio_fetcher.py` pass (209) - Added: remote-error-does-not-fall-back-to-local; updated the two half-config factory tests to expect a raise. ## Review - [x] CodeRabbit CLI review completed locally (1 major finding: clear cached results on failure — fixed) @coderabbitai ignore --- 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) --- backend/services/audio_search_service.py | 15 ++++++++++----- backend/tests/test_audio_search.py | 16 ++++++++++++++++ karaoke_gen/audio_fetcher.py | 17 +++++++++++++---- pyproject.toml | 2 +- tests/unit/test_audio_fetcher.py | 16 ++++++++-------- 5 files changed, 48 insertions(+), 18 deletions(-) diff --git a/backend/services/audio_search_service.py b/backend/services/audio_search_service.py index b240913f..a6c1a98c 100644 --- a/backend/services/audio_search_service.py +++ b/backend/services/audio_search_service.py @@ -368,12 +368,17 @@ class AudioSearchService: return results except FlacfetchServiceError as e: - logger.warning(f"Remote flacfetch search failed, falling back to local: {e}") - # Fallback to local search + # flacfetch is the sole downloader. The remote service was explicitly + # configured, so a failure here must NOT silently downgrade to the + # local YouTube-only fetcher — that hides the outage and ships a worse + # source than the user expected (the 2026-06-08 incident class). + # Fail loudly. (Fallback audit 2026-06-09, Theme 1.) + logger.error(f"Remote flacfetch search failed (not falling back to local): {e}") + # Clear cached state so a later download() can't consume stale results + # from a previous successful search on this (singleton) instance. self._remote_search_id = None - results = self._fetcher.search(artist, title) - self._cached_results = results - return results + self._cached_results = [] + raise AudioSearchError(f"Remote flacfetch search failed: {e}") from e def select_best(self, results: List[AudioSearchResult]) -> int: """ diff --git a/backend/tests/test_audio_search.py b/backend/tests/test_audio_search.py index d3566591..373e2455 100644 --- a/backend/tests/test_audio_search.py +++ b/backend/tests/test_audio_search.py @@ -321,6 +321,22 @@ class TestAudioSearchServiceSearch: assert "No results found" in str(exc_info.value) + def test_remote_search_failure_does_not_fall_back_to_local(self): + """A remote flacfetch error must fail loudly, not silently downgrade to local YouTube.""" + from backend.services.flacfetch_client import FlacfetchServiceError + + service = AudioSearchService(red_api_key=None, red_api_url=None, ops_api_key=None, ops_api_url=None) + mock_remote = Mock() + mock_remote.search = AsyncMock(side_effect=FlacfetchServiceError("remote service down")) + service._remote_client = mock_remote + service._fetcher = Mock() # local fetcher — must NOT be used as a silent fallback + + with pytest.raises(AudioSearchError, match="Remote flacfetch search failed"): + service.search("ABBA", "Waterloo") + + # Critical: we did NOT silently fall back to the local YouTube-only fetcher. + service._fetcher.search.assert_not_called() + def test_search_multiple_results(self): """Test search returns multiple results with correct indices.""" mock_results = [] diff --git a/karaoke_gen/audio_fetcher.py b/karaoke_gen/audio_fetcher.py index badea6db..3bc86c0f 100644 --- a/karaoke_gen/audio_fetcher.py +++ b/karaoke_gen/audio_fetcher.py @@ -1816,11 +1816,20 @@ def create_audio_fetcher( logger=logger, ) elif api_url and not api_key: - if logger: - logger.warning("FLACFETCH_API_URL is set but FLACFETCH_API_KEY is not - falling back to local mode") + # Half-configured remote flacfetch is almost always a deploy/secret typo. + # Silently using local mode masks the misconfiguration — fail loudly so + # the operator fixes it. (Fallback audit 2026-06-09, Theme 1.) + raise AudioFetcherError( + "FLACFETCH_API_URL is set but FLACFETCH_API_KEY is not. Remote flacfetch " + "is half-configured — set both (or neither, for local mode). Refusing to " + "silently fall back to local mode and mask the misconfiguration." + ) elif api_key and not api_url: - if logger: - logger.warning("FLACFETCH_API_KEY is set but FLACFETCH_API_URL is not - falling back to local mode") + raise AudioFetcherError( + "FLACFETCH_API_KEY is set but FLACFETCH_API_URL is not. Remote flacfetch " + "is half-configured — set both (or neither, for local mode). Refusing to " + "silently fall back to local mode and mask the misconfiguration." + ) # Use local flacfetch library return FlacFetchAudioFetcher( diff --git a/pyproject.toml b/pyproject.toml index db60c9d7..0f664170 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "karaoke-gen" -version = "0.196.5" +version = "0.196.6" description = "Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens." authors = ["Andrew Beveridge "] license = "MIT" diff --git a/tests/unit/test_audio_fetcher.py b/tests/unit/test_audio_fetcher.py index ed8aac9c..cc1e2269 100644 --- a/tests/unit/test_audio_fetcher.py +++ b/tests/unit/test_audio_fetcher.py @@ -2342,20 +2342,20 @@ class TestCreateAudioFetcherRemoteSelection: assert fetcher.api_key == "custom_key" @patch.dict(os.environ, {"FLACFETCH_API_URL": "http://localhost:8080"}, clear=False) - def test_falls_back_to_local_without_api_key(self): - """Test factory falls back to local when only URL is set.""" + def test_half_configured_url_only_raises(self): + """Half-configured remote (URL only) must fail loudly, not silently use local.""" # Clear FLACFETCH_API_KEY if it exists with patch.dict(os.environ, {"FLACFETCH_API_KEY": ""}, clear=False): - fetcher = create_audio_fetcher() - assert isinstance(fetcher, FlacFetchAudioFetcher) + with pytest.raises(AudioFetcherError, match="FLACFETCH_API_KEY is not"): + create_audio_fetcher() @patch.dict(os.environ, {"FLACFETCH_API_KEY": "test_key"}, clear=False) - def test_falls_back_to_local_without_api_url(self): - """Test factory falls back to local when only key is set.""" + def test_half_configured_key_only_raises(self): + """Half-configured remote (key only) must fail loudly, not silently use local.""" # Clear FLACFETCH_API_URL if it exists with patch.dict(os.environ, {"FLACFETCH_API_URL": ""}, clear=False): - fetcher = create_audio_fetcher() - assert isinstance(fetcher, FlacFetchAudioFetcher) + with pytest.raises(AudioFetcherError, match="FLACFETCH_API_URL is not"): + create_audio_fetcher() @patch.dict(os.environ, {}, clear=True) def test_creates_local_fetcher_by_default(self):