Struct HybridRepository 

pub struct HybridRepository {
    online: Arc<OnlineRepository>,
    offline: Arc<OfflineRepository>,
}

Hybrid repository combining online and offline data sources

Uses cache-first parallel racing strategy:

• Runs SQLite cache and HTTP server queries in parallel
• Cache has 100ms timeout for fast feedback
• Returns cache result if it has meaningful content
• Falls back to server result if cache is empty/stale

@req: UR-002 - Access media when online or offline @req: DR-012 - Local database for media metadata cache @req: DR-013 - Repository pattern for online/offline data access

Fields

online: Arc<OnlineRepository>

offline: Arc<OfflineRepository>

Implementations

impl HybridRepository

pub fn new(online: OnlineRepository, offline: OfflineRepository) -> Self

pub fn user_id(&self) -> &str

The signed-in user this repository acts for.

TRACES: UR-069 | DR-120

pub async fn download_bytes(&self, url: &str) -> Result<Vec<u8>, String>

Download raw bytes from a URL using the shared authenticated HTTP client. Delegates to online repository for connection reuse and proper auth.

pub async fn prune_stale_catalog( &self, cutoff: &str, item_types: &[String], ) -> Result<usize, RepoError>

Remove catalog entries the server no longer has. Cache-only, so it goes straight to the offline repository. Callers must only invoke this after a crawl in which every library succeeded — see OfflineRepository::prune_stale_catalog for why a partial crawl must not sweep.

TRACES: UR-065 | DR-110

pub async fn get_jray_actors( &self, item_id: &str, t: f64, ) -> Result<Vec<JRayActor>, RepoError>

Query the JRay plugin for actors on screen at time t. Online-only (the plugin lives on the Jellyfin server); empty when JRay isn’t present.

pub async fn get_video_stream_url( &self, item_id: &str, media_source_id: Option<&str>, audio_stream_index: Option<i32>, ) -> Result<String, RepoError>

Get video stream URL. This method is online-only since offline playback uses local file paths.

Takes no start position: the URL is an HLS playlist spanning the whole item, and a position on it would 400 every segment — see OnlineRepository::get_video_stream_url. Resume by seeking after load.

pub async fn get_stream_selection( &self, item_id: &str, media_source_id: Option<&str>, audio_stream_index: Option<i32>, ) -> Result<StreamSelection, RepoError>

Decide what stream to play and describe it fully — the DR-225 contract.

Online-only for the same reason as get_video_stream_url: an offline item is a file on disk, and the caller builds [StreamSelection::local_file] for it rather than negotiating anything.

TRACES: UR-070, UR-079 | DR-225, DR-227, DR-228

pub async fn get_audio_only_stream_url_for_video( &self, item_id: &str, media_source_id: Option<&str>, start_time_seconds: Option<f64>, audio_stream_index: Option<i32>, ) -> Result<String, RepoError>

Get an audio-only stream URL for a video item (background-audio handoff). Online-only, like get_video_stream_url.

TRACES: UR-040 | JA-032

pub async fn get_album_tracks( &self, album_id: &str, ) -> Result<Vec<MediaItem>, RepoError>

Every track of an album, asked of the server rather than the cache.

Deliberately not get_items, which is cache-first: it answers from SQLite the moment the cache has any content. That is right for browsing and wrong for deciding what to download, because a partial or unlinked cache then decides how much of the album gets queued while the user is told the whole album is downloading. Downloading is the one operation that must know the album’s complete contents.

Errors when the server cannot answer (offline); the caller falls back to the local catalog and the rows are queued either way, resolving on reconnect. Server results are written back to the cache, so browsing benefits from the round trip too.

TRACES: UR-018, UR-055 | DR-173

pub async fn get_items_unfiltered( &self, parent_id: &str, options: Option<GetItemsOptions>, ) -> Result<SearchResult, RepoError>

Immediate children of a container with the user’s browsing exclusions not applied.

Exists for the exclusion picker in settings. Everything else in this repository hides what the user has hidden, which would make the setting one-way: a folder already excluded would vanish from the list of folders to exclude and could never be un-hidden. Server-first so the picker sees the real library, falling back to the cache when unreachable.

TRACES: UR-076 | DR-209

pub async fn search_cache_only( &self, query: &str, options: Option<SearchOptions>, ) -> Result<SearchResult, RepoError>

Search only the local SQLite cache (downloaded content).

Fast (100ms timeout) — used to render instant results before the server responds. Returns an empty result rather than erroring on timeout so the caller can still fall through to the server.

pub async fn get_favorites_cache_only( &self, scope: SearchScope, options: Option<GetItemsOptions>, ) -> Result<SearchResult, RepoError>

Favourites held locally, without touching the server. Backs the instant leg of the two-phase favourites read in the command layer.

TRACES: UR-067 | DR-115

pub async fn get_favorites_server_only( &self, scope: SearchScope, options: Option<GetItemsOptions>, ) -> Result<SearchResult, RepoError>

Favourites straight from the server, persisted to the cache on the way through — which is also what mirrors their favourite flags into user_data (DR-114), so the next offline read agrees with the server.

TRACES: UR-067 | DR-115

pub async fn cache_items_from_server( &self, parent_id: &str, options: Option<GetItemsOptions>, ) -> Result<Vec<MediaItem>, RepoError>

Fetch a folder’s items from the live server and persist them to the offline cache synchronously (unlike get_items, which saves in a fire-and-forget background task after a 100ms cache race).

Used by the full-catalog pre-sync (sync_full_catalog) to deterministically walk every library while online so the whole catalog is browsable — greyed out — offline. Returns the items fetched so the caller can recurse into containers. Server-only: errors if unreachable.

pub async fn get_downloaded_items( &self, parent_id: &str, options: Option<GetItemsOptions>, ) -> Result<SearchResult, RepoError>

Browse downloaded content only — the dedicated Downloads surface.

Bypasses the cache/server merge entirely and reads the offline repository directly, so an empty result is authoritative (“nothing downloaded here”) and never falls through to the server (DR-080). Available online too — a user who is reachable still wants to browse what’s on the device.

TRACES: UR-055 | DR-082, DR-083

pub async fn get_downloaded_libraries(&self) -> Result<Vec<Library>, RepoError>

Libraries that contain downloaded content (offline-only, authoritative).

TRACES: UR-055 | DR-082

pub async fn get_download_disk_usage( &self, ) -> Result<DownloadDiskUsage, RepoError>

On-disk usage of downloaded content, for the disk-usage display.

TRACES: UR-056 | DR-085

pub async fn search_server_only( &self, query: &str, options: Option<SearchOptions>, ) -> Result<SearchResult, RepoError>

Search only the live Jellyfin server (full library).

pub fn merge_search_results( cache: SearchResult, server: SearchResult, ) -> SearchResult

Merge cache and server search results into a single de-duplicated list.

Ordering: local (cached/downloaded) items first, then server-only items appended. On a duplicate id, the server’s item wins (fresher, more complete metadata) but keeps the local item’s earlier position.

async fn parallel_race<T, F1, F2>( &self, cache_future: F1, server_future: F2, ) -> Result<T, RepoError>

where T: MeaningfulContent + ExcludeHidden + Clone + Send + 'static, F1: Future<Output = Result<T, RepoError>> + Send, F2: Future<Output = Result<T, RepoError>> + Send,

Cache-first query: try cache, fall back to server on miss.

1. Check cache (100ms timeout applied by caller via cache_with_timeout)
2. If cache has meaningful content → return immediately (fast path)
3. If cache is empty/stale → query server (fresh data)
4. If server fails → return cache even if empty (offline fallback)

Both legs are passed through ExcludeHidden before the “does the cache have content?” question is asked. This is the single place the cache and server results of a cache-first query converge, so applying the user’s browsing exclusions here covers every query built on it at once — and filtering before the content check is what makes a cache page holding nothing but hidden items fall through to the server instead of being served as an empty listing.

@req: UR-002 - Access media when online or offline @req: DR-013 - Repository pattern for online/offline data access

TRACES: UR-002, UR-076 | DR-013, DR-209

async fn race_with_refresh<T, F1, F2, R>( &self, cache_future: F1, server_future: F2, on_cache_hit: R, ) -> Result<T, RepoError>

where T: MeaningfulContent + ExcludeHidden + Clone + Send + 'static, F1: Future<Output = Result<T, RepoError>> + Send, F2: Future<Output = Result<T, RepoError>> + Send, R: FnOnce(),

Self::parallel_race, plus a callback fired on the fast path so the caller can refresh the cache in the background.

A plain cache hit answers from data that may be arbitrarily old, which is right for the response and wrong for what it leaves behind: per-user state (watch positions, favourites) only reaches the local tables when a server result is cached, so a surface that always hits cache never learns what another device did. get_items had a bespoke version of this; this is the same idea, reusable.

The callback runs only on a cache hit — on a miss the server result is already being fetched and cached by the normal path.

TRACES: UR-002, UR-025, UR-076 | DR-155, DR-209

async fn cache_with_timeout<T>( &self, future: impl Future<Output = Result<T, RepoError>> + Send, ) -> Result<T, RepoError>

Simple timeout wrapper for cache queries (100ms timeout)

@req: DR-013 - Repository pattern (cache-first with timeout)

Trait Implementations

impl MediaRepository for HybridRepository

fn get_item<'life0, 'life1, 'async_trait>( &'life0 self, item_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<MediaItem, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

A single item, cache-first — and, on a cache hit, refreshed in the background so the stored copy keeps up with the server.

The background refresh is what carries per-user state home: caching an item runs mirror_user_data, which is the only path by which a watch position set on another device reaches the local user_data row the resume check reads. Without it a cache hit returned this device’s own stale position forever and cross-device resume silently did nothing — get_items already refreshes this way, so browsing a season worked while opening the episode directly did not.

The refreshed value lands for the next read rather than this one: the point of the cache-first race is to answer immediately.

TRACES: UR-025, UR-002 | DR-155 | UT-152

fn get_favorites<'life0, 'async_trait>( &'life0 self, scope: SearchScope, options: Option<GetItemsOptions>, ) -> Pin<Box<dyn Future<Output = Result<SearchResult, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

TRACES: UR-067 | DR-115

fn get_libraries<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<Library>, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get all libraries

fn get_items<'life0, 'life1, 'async_trait>( &'life0 self, parent_id: &'life1 str, options: Option<GetItemsOptions>, ) -> Pin<Box<dyn Future<Output = Result<SearchResult, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get items in a library or parent

fn get_latest_items<'life0, 'life1, 'async_trait>( &'life0 self, parent_id: &'life1 str, limit: Option<usize>, ) -> Pin<Box<dyn Future<Output = Result<Vec<MediaItem>, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get latest items in a library

fn get_resume_items<'life0, 'life1, 'async_trait>( &'life0 self, parent_id: Option<&'life1 str>, limit: Option<usize>, ) -> Pin<Box<dyn Future<Output = Result<Vec<MediaItem>, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get resume items (continue watching/listening)

fn get_next_up_episodes<'life0, 'life1, 'async_trait>( &'life0 self, series_id: Option<&'life1 str>, limit: Option<usize>, ) -> Pin<Box<dyn Future<Output = Result<Vec<MediaItem>, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get next up episodes

fn get_recently_played_audio<'life0, 'async_trait>( &'life0 self, limit: Option<usize>, ) -> Pin<Box<dyn Future<Output = Result<Vec<MediaItem>, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get recently played audio

fn get_resume_movies<'life0, 'async_trait>( &'life0 self, limit: Option<usize>, ) -> Pin<Box<dyn Future<Output = Result<Vec<MediaItem>, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get resume movies

fn get_rediscover_albums<'life0, 'life1, 'async_trait>( &'life0 self, parent_id: Option<&'life1 str>, limit: Option<usize>, ) -> Pin<Box<dyn Future<Output = Result<Vec<MediaItem>, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get albums the user has played, but not recently (“rediscover” / haven’t listened to in a while). Returns albums sorted by least-recently played first, optionally restricted to a parent library.

fn get_genres<'life0, 'life1, 'async_trait>( &'life0 self, parent_id: Option<&'life1 str>, ) -> Pin<Box<dyn Future<Output = Result<Vec<Genre>, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get genres

fn search<'life0, 'life1, 'async_trait>( &'life0 self, query: &'life1 str, options: Option<SearchOptions>, ) -> Pin<Box<dyn Future<Output = Result<SearchResult, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Search for items

fn get_playback_info<'life0, 'life1, 'async_trait>( &'life0 self, item_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<PlaybackInfo, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get playback info for streaming

fn get_audio_stream_url<'life0, 'life1, 'async_trait>( &'life0 self, item_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get audio stream URL for a track

fn get_audio_only_stream_url_for_video<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, item_id: &'life1 str, media_source_id: Option<&'life2 str>, start_time_seconds: Option<f64>, audio_stream_index: Option<i32>, ) -> Pin<Box<dyn Future<Output = Result<String, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Get an audio-only stream URL for a video item (background-audio handoff).

fn get_live_tv_channels<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<MediaItem>, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get Live TV channels (broadcast / IPTV) for browsing.

fn get_channels<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<SearchResult, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get the root list of plugin “Channels” (Jellyfin Channels feature). Drill-down into a channel reuses get_items(channel_id, ...).

fn open_live_stream<'life0, 'life1, 'async_trait>( &'life0 self, item_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<LiveStreamInfo, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Open a live stream (Live TV channel or live channel item) for playback.

fn report_playback_start<'life0, 'life1, 'async_trait>( &'life0 self, item_id: &'life1 str, position_ticks: i64, ) -> Pin<Box<dyn Future<Output = Result<(), RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Report playback start

fn report_playback_progress<'life0, 'life1, 'async_trait>( &'life0 self, item_id: &'life1 str, position_ticks: i64, ) -> Pin<Box<dyn Future<Output = Result<(), RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Report playback progress

fn report_playback_stopped<'life0, 'life1, 'async_trait>( &'life0 self, item_id: &'life1 str, position_ticks: i64, ) -> Pin<Box<dyn Future<Output = Result<(), RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Report playback stopped

fn get_image_url( &self, item_id: &str, image_type: ImageType, options: Option<ImageOptions>, ) -> String

Get image URL (synchronous - just constructs URL)

fn get_subtitle_url( &self, item_id: &str, media_source_id: &str, stream_index: i32, format: &str, ) -> String

Get subtitle URL (synchronous - just constructs URL) Called by frontend via Tauri invoke (getSubtitleUrl in VideoPlayer.svelte)

fn get_video_download_url( &self, item_id: &str, quality: &str, media_source_id: Option<&str>, source_audio_codec: Option<&str>, ) -> String

Build the URL a video download is fetched from. Synchronous — it only constructs a URL, so it stays testable without a server. Reach it through resolve_video_download_url rather than calling it directly.

fn mark_favorite<'life0, 'life1, 'async_trait>( &'life0 self, item_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Mark item as favorite

fn unmark_favorite<'life0, 'life1, 'async_trait>( &'life0 self, item_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Unmark item as favorite

fn clear_watch_history<'life0, 'life1, 'async_trait>( &'life0 self, item_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Erase the viewer’s watch history for an item: clear its played flag and its resume position. On a container (series, season) this applies to everything inside it, so a series is returned to “never watched” and reopens on its premiere.

fn mark_played<'life0, 'life1, 'async_trait>( &'life0 self, item_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Mark an item played — the inverse of clear_watch_history. Needed by the sync-queue drain, which replays mark_played rows queued while the server was unreachable; reporting a stop at a made-up position was the previous stand-in and does not set the played flag reliably.

fn get_person<'life0, 'life1, 'async_trait>( &'life0 self, person_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<MediaItem, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get person details

fn get_items_by_person<'life0, 'life1, 'async_trait>( &'life0 self, person_id: &'life1 str, options: Option<GetItemsOptions>, ) -> Pin<Box<dyn Future<Output = Result<SearchResult, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get items by person (filmography)

fn get_similar_items<'life0, 'life1, 'async_trait>( &'life0 self, item_id: &'life1 str, limit: Option<usize>, ) -> Pin<Box<dyn Future<Output = Result<SearchResult, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get similar/related items for a movie or show

fn create_playlist<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, name: &'life1 str, item_ids: &'life2 [String], ) -> Pin<Box<dyn Future<Output = Result<PlaylistCreatedResult, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Create a new playlist on the server

fn delete_playlist<'life0, 'life1, 'async_trait>( &'life0 self, playlist_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Delete a playlist

fn rename_playlist<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, playlist_id: &'life1 str, name: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Rename a playlist

fn get_playlist_items<'life0, 'life1, 'async_trait>( &'life0 self, playlist_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<PlaylistEntry>, RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get playlist items with PlaylistItemId (needed for remove/reorder)

fn add_to_playlist<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, playlist_id: &'life1 str, item_ids: &'life2 [String], ) -> Pin<Box<dyn Future<Output = Result<(), RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Add items to a playlist

fn remove_from_playlist<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, playlist_id: &'life1 str, entry_ids: &'life2 [String], ) -> Pin<Box<dyn Future<Output = Result<(), RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Remove items from a playlist using entry IDs (PlaylistItemId, NOT media item IDs)

fn move_playlist_item<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, playlist_id: &'life1 str, item_id: &'life2 str, new_index: u32, ) -> Pin<Box<dyn Future<Output = Result<(), RepoError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Move a playlist item to a new position