Struct OfflineRepository 

pub struct OfflineRepository {
    db_service: Arc<RusqliteService>,
    server_id: String,
    user_id: String,
}

Fields

db_service: Arc<RusqliteService>

server_id: String

user_id: String

Implementations

impl OfflineRepository

pub fn new( db_service: Arc<RusqliteService>, server_id: String, user_id: String, ) -> Self

fn cached_item_to_media_item( item: CachedItem, user_data: Option<UserData>, ) -> MediaItem

Helper to convert CachedItem from storage to MediaItem

async fn get_user_data(&self, item_id: &str) -> Option<UserData>

Get user data for an item (playback position, favorite, etc.)

impl OfflineRepository

const LIBRARY_HOLDS_ITEM: &'static str = "( (l.collection_type = 'music' AND i.item_type IN ('MusicAlbum', 'MusicArtist', 'Audio')) OR (l.collection_type = 'movies' AND i.item_type = 'Movie') OR (l.collection_type = 'tvshows' AND i.item_type IN ('Series', 'Season', 'Episode')) OR l.collection_type IS NULL OR l.collection_type NOT IN ('music', 'movies', 'tvshows') )"

SQL fragment: the set of item ids that are “on the device” — playable items with a completed download, plus containers (album/series/season) that have at least one downloaded child. This is the get_items CTE with the synced-but-not-downloaded catalog branch deliberately excluded, so it is authoritative regardless of the process-wide catalog-browse flag.

Whether cached item i belongs to library l, decided by media kind.

The cache leaves library_id/parent_id NULL on every item ([[offline-libraries-never-cached]]), so there is no link to follow: a library’s collection_type and an item’s item_type are the only things that can associate them. This is Jellyfin taxonomy and therefore lives in Rust, never in the frontend.

It is a named constant because it is needed in two places that must agree — which library appears in the Downloaded list, and which items appear inside it. They disagreed: the listing query used this mapping while the browse query only checked that the requested library existed, so opening any library showed every downloaded top-level item on the server.

A library of some other (or unknown) type keeps everything, since there is no mapping to narrow it by and hiding its contents would be worse.

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

const DOWNLOADED_ITEMS_CTE: &'static str = " WITH downloaded_items AS ( SELECT DISTINCT i.id FROM items i INNER JOIN downloads d ON i.id = d.item_id WHERE d.status = 'completed' AND i.item_type IN ('Audio', 'Movie', 'Episode') UNION SELECT DISTINCT i.id FROM items i INNER JOIN items children ON (children.parent_id = i.id OR children.album_id = i.id OR children.season_id = i.id OR children.series_id = i.id) INNER JOIN downloads d ON children.id = d.item_id WHERE d.status = 'completed' AND i.item_type IN ('MusicAlbum', 'Series', 'Season', 'BoxSet', 'Folder', 'CollectionFolder') )"

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

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

Remove catalog entries the server no longer has (mark-and-sweep).

save_to_cache stamps every row it writes with a fresh synced_at, so after a complete crawl anything still on the server carries a timestamp newer than cutoff (taken before the crawl began) and anything deleted server-side kept its older one. Sweeping by timestamp avoids binding the crawl’s entire id set, which would blow past SQLite’s variable limit on a large library.

Three exclusions, each load-bearing:

• Only item_types the crawl actually requested. The crawl asks for CATALOG_ITEM_TYPES; rows of any other type (artists, playlists, the Folder parent stubs save_to_cache inserts) are never refreshed by it, so sweeping by age alone would delete every one of them.
• Anything a completed download depends on — the downloaded item itself, and any container with a downloaded child. The user has those bytes on disk; dropping the row would orphan the file.
• Callers must only invoke this after a crawl in which every library succeeded. sync_full_catalog is best-effort per library, and items.parent_id is ON DELETE CASCADE, so sweeping after a partial crawl could cascade an entire series away because one request timed out.

Returns the number of rows removed.

TRACES: UR-065 | DR-110 | UT-113

async fn search_people( &self, fts_query: &str, limit: usize, ) -> Result<Vec<MediaItem>, RepoError>

Full-text search over cached people (cast and crew).

People are stored in their own table rather than in items, so search has to look them up separately and adapt them to MediaItem. Availability gating deliberately does not apply: a person is metadata, never a download, so there is nothing to be offline about.

TRACES: UR-065, UR-060 | DR-111 | UT-114

pub async fn save_to_cache( &self, parent_id: &str, items: &[MediaItem], ) -> Result<usize, RepoError>

Save browsed items to cache for faster subsequent loading

This persists metadata for items that were browsed (not necessarily downloaded). Items are marked with current timestamp for freshness tracking.

async fn save_to_cache_impl( &self, parent_id: &str, items: &[MediaItem], now: &str, ) -> Result<usize, RepoError>

async fn mirror_user_data( &self, item: &MediaItem, now: &str, ) -> Result<(), RepoError>

Mirror the server’s per-user state for an item into the local user_data table, so favourites marked — and positions watched — on any other client are visible here, including offline, where the local table is the only source.

The WHERE user_data.pending_sync = 0 on the conflict clause is the conflict rule: a change made while the server was unreachable is still waiting to be pushed, and must not be clobbered by the stale value the server is still reporting. For a position that means it is never pulled backwards by a server that has not yet heard where we got to.

Each field is mirrored only when the server actually reported it — COALESCE(excluded.x, user_data.x) keeps the stored value for anything absent, and a row with neither field is skipped outright rather than written as zeroes, which would fabricate an “unfavourited, unwatched” record from an endpoint that simply omits UserData.

The position half is what makes cross-device resume work: the resume check reads this table alone, so before it was mirrored an item watched elsewhere resumed from whatever this device last saw, or not at all.

TRACES: UR-025, UR-069 | DR-114, DR-155 | UT-102, UT-152

pub async fn save_libraries_to_cache( &self, libraries: &[Library], ) -> Result<usize, RepoError>

Cache the library (view) list from the server into the local database. Called by HybridRepository after a successful online fetch so the list is available offline. Without this, the libraries table stays empty and offline startup shows no libraries at all.

pub async fn save_genres_to_cache( &self, parent_id: Option<&str>, genres: &[Genre], ) -> Result<usize, RepoError>

Cache the full server genre catalog for a library, so offline (and the hybrid cache-first race) can return the complete list instead of only the genres derivable from locally-cached albums. Replaces the scope’s rows wholesale so genres removed on the server don’t linger.

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

Downloaded-only browse: items under parent_id that are on the device.

Unlike MediaRepository::get_items, this never includes the synced-but-not-downloaded catalog and never consults the process-wide INCLUDE_CATALOG_BROWSE flag — it is the dedicated Downloads surface. An empty result is authoritative (“nothing downloaded here”), so the hybrid repo must call this directly rather than racing the server.

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

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

Libraries that contain at least one downloaded item. Libraries with nothing on the device are omitted, so the Downloaded surface only lists libraries the user actually has offline content in.

TRACES: UR-055 | DR-082

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

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

Returns one entry per container or leaf that appears in the Downloaded browse: a leaf’s own file_size, a container’s summed downloaded descendants — plus the device total and item (leaf) count. This is pure aggregation over downloads.file_size, not new tracking.

TRACES: UR-056 | DR-085

pub async fn save_playlist_items_to_cache( &self, playlist_id: &str, entries: &[PlaylistEntry], ) -> Result<(), RepoError>

Cache playlist items from server into local database Called by HybridRepository after fetching from online

Trait Implementations

impl MediaRepository for OfflineRepository

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,

Favourites held locally — the ones mirrored from the server by save_to_cache plus anything favourited on this device.

Gated by the same available_items rules as browsing, so with “Show all server media” off this returns favourites that are actually on the device rather than the whole favourited catalog (DR-080).

TRACES: UR-067 | DR-115 | UT-101

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_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,

Get a single item by ID

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_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_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_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