fix(offline): offline mode no longer needs the network

Three defects made "offline" depend on a server it could not reach.

A downloaded film would not play offline. The player found the file on disk,
then asked the server for the item's PlaybackInfo only to read its
media-source id; with no network that retried for seven seconds and failed,
and the file was never opened. A completed download now answers playback
info from its download row — local path, direct play, item id as media
source — and the hybrid repository consults it before the network.

"More info" on a downloaded show failed with "Failed to load item". The
cache is one SQLite connection behind one mutex, so any write in progress
(the catalog sync at every launch, a download finishing) pushes a read past
the 100 ms fast path — and get_items, the library list, genres and playlist
items discarded such a read, waited on the server, and returned its error
over data sitting on disk. They now keep the read running and wait for it
when the server fails; the cache-only reads (search, favourites) simply
await the cache, having no server to fall back from.

Next Up went only to the server, and the TV landing page loads it in one
Promise.all with its other rows, so offline it blanked the whole page. It now
falls back to the cache.

Each fix has a test that failed first against an unreachable server (and, for
the cache, a database held past the fast path).

DR-294, UT-260, UT-261, UT-263.
This commit is contained in:
2026-09-22 22:22:14 -04:00
parent bed1030443
commit 5259b47cf3
3 changed files with 495 additions and 42 deletions
@@ -186,6 +186,62 @@ Per-item disk usage comes from `repository_get_download_disk_usage`
Downloaded browse cards, detail pages, the device total and the remove
confirmation (DR-085).
## What a Video Download Fetches
**TRACES**: UR-071, UR-004 | DR-171, DR-293
An `original`-quality download is the server's untouched file (`Static=true`)
unless its audio cannot be decoded by **the renderer that will play it**
`renderer_can_decode_audio`, DR-234's per-platform answer. Only then is the
server asked to re-encode the audio on the way down (`allowVideoStreamCopy`
keeps the picture byte-for-byte).
The distinction matters because a transcode is generated as it is sent: no
`Content-Length`, `Range` ignored. It measured ~1 MB/s and restarted from byte
zero on every network blip, against a direct copy that moved a 910 MB episode in
94 s with no retries. On Android the renderer is ExoPlayer with the FFmpeg
extension ([05-platform-backends.md](05-platform-backends.md)), which decodes
AC-3/E-AC-3/DTS/TrueHD, so Android downloads are always the direct copy. On
Linux the webview still renders video and the transcode still applies.
The policy used to judge against the *webview's* codec list on every platform
(DR-171), because a download outlives the native-video setting that was active
when it arrived. That reasoning is why Android's webview video path was removed
rather than merely defaulted off: a file downloaded as the original must never
meet a renderer that cannot decode it.
## Offline Means No Network
**TRACES**: UR-002, UR-071 | DR-294
Three defects made "offline" depend on the network; the invariants that replace
them:
- **A download plays without the server.** Playing a downloaded item asked the
server for its `PlaybackInfo` only to read the media-source id; offline that
retried for seven seconds, failed, and the file was never opened.
`OfflineRepository::local_playback_info` answers for any completed download of
the current user — local path, direct play, item id as media source (a download
names no source, so the server served its default, which carries the item's id)
— and `HybridRepository::get_playback_info` consults it **first**.
- **A slow cache read is waited for, never discarded.** The cache is one SQLite
connection behind one mutex, so any write in progress (the catalog sync that
starts at every launch, a download finishing) pushes a read past the 100 ms fast
path. `get_items`, the library list, genres and playlist items used to discard
such a read, wait for the server, and — offline — return its error over data on
disk; "More info" on a downloaded show failed that way. They now start the read
with `cache_try` (which keeps it running) and `settle` on it when the server
fails. Cache-only reads (search, favourites) have no server to fall back from,
so they simply await the cache.
- **Server-only sections degrade, they do not fail a page.** Next Up went only to
the server, and the TV landing page loads it in one `Promise.all`, so offline it
blanked the whole page. It now falls back to the cache when the server cannot
answer.
What still needs the server, deliberately: streaming anything not downloaded,
live TV and channels, reporting playback, and edits (favourites, playlists,
played state).
## Download Commands
**Location**: `src-tauri/src/commands/download/``mod.rs` (the commands below), `pinning.rs`, `smart_cache.rs`