fix(fallbacks): T1 — flacfetch sole downloader, no silent YouTube downgrade (#806)

## 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) <noreply@anthropic.com>
This commit is contained in:
Andrew Beveridge ☄️andClaude Opus 4.8 authored and GitHub committed 2026-08-22 18:35:12 -04:00
1 parent 27a5d8fdff
commit 5fff6d67b0
5 files changed
+48 -18

No files matched your search

+10 -5
View File
@@ -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:
"""
+16
View File
@@ -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 = []
+13 -4
View File
@@ -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(
+1 -1
View File
@@ -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 <andrew@beveridge.uk>"]
license = "MIT"
+8 -8
View File
@@ -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):