fix: resolve prefetch timeout and retry path failures (#67)

[danmunz]

Problem

Nitrowolf's 525-artwork collection gets ~150 cached thumbnails but the remaining ~375 always show "Tap to Retry". v1.3.0 addressed connection management but the overnight prefetch still fails 100%.

Root Causes Identified

1. _PREFETCH_TIMEOUT = 5 too short — The D2D socket protocol (WS request → TV processing → D2D connection info → TCP socket → file transfer) needs ~10-18s. The 5s timeout caused every prefetch attempt to fail immediately. The ~150 cached thumbnails came from get_thumbnail_list (batch call, 18s timeout) — the individual prefetch path has likely never succeeded.

2. "Tap to retry" used batch endpoint — showThumbError → loadThumbnailBatch([cid]) → POST /api/thumbnails, subject to circuit breaker. Should use GET /api/thumbnail/{cid} (18s timeout, 3 retries, no circuit breaker).

3. Invisible logging — All prefetch failures logged at DEBUG level, invisible at default INFO. Zero visibility into what's happening.

4. Startup retry chain breaks permanently — Auto-retry only fired for source="startup", so user-triggered prefetches never scheduled retries. The retry also silently skipped if another prefetch was running.

5. retryAllThumbnails race — Fire-and-forget /thumbnails/retry + simultaneous loadThumbnailBatch → first batch immediately re-trips circuit breaker that was just reset.

Changes

File	Change
server.py	Remove _PREFETCH_TIMEOUT — use default 18s timeout
server.py	Prefetch logging: failures→WARNING, successes→INFO, zero-cached→WARNING
server.py	Auto-retry fires regardless of source, waits for in-progress prefetch
server.py	Add GET /api/thumbnails/diag — cache count, prefetch state, circuit breaker status
index.html	"Tap to retry" → retrySingleThumb(cid) using GET /api/thumbnail/{cid}
index.html	retryAllThumbnails → async, await retry before polling, set fallback mode
tests/	5 new tests: timeout removal, constant absence, diag endpoint fields/cache/breaker

Tradeoff

Worst-case lock hold before abort increases from 55s to 120s. This is acceptable because:

• 5s timeout = 0% prefetch success (nothing ever caches)
• 18s timeout = actual D2D completion possible
• Abort cap (5 consecutive failures) still limits damage
• Lock is released between items (PR fix: persistent TV connection + eliminate concurrent socket races #68 fix preserved)

Testing

PYTHONPATH=. uv run pytest -x -q
120 passed, 6 xfailed

Known Limitations

• If the SSL EOF error (UNEXPECTED_EOF_WHILE_READING) affects individual get_thumbnail() calls too (not just get_thumbnail_list), then the timeout fix alone won't resolve Nitrowolf's issue. The logging upgrade will make this visible.
• retryAllThumbnails still has a timing window: 8 retries × 3s = 24s polling, but 400 thumbnails × 2-18s = much longer prefetch. Each "Retry All" click will show some more thumbnails as they cache.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8ff5c3a769

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Define the API URL for single-thumbnail retries

When a user clicks a failed thumbnail, this new path evaluates BASE before issuing the request, but there is no BASE definition anywhere in index.html (the existing api() helper hardcodes the /api prefix). In that retry scenario the click handler throws a ReferenceError, so the intended GET /api/thumbnail/{cid} request is never sent and “Tap to retry” remains broken.

Useful? React with 👍 / 👎.