Module catalog 

Tauri commands for the offline “browse & queue” feature.

TRACES: UR-002, UR-007, UR-024 | JA-004, JA-016 | DR-012, DR-027

Two backend pieces support browsing the full server catalog while offline and queueing downloads that fire on reconnect:

• sync_full_catalog walks every library while online and persists all items to the offline cache so the whole catalog is browsable (greyed out) offline. It reuses [HybridRepository::cache_items_from_server], which in turn reuses OfflineRepository::save_to_cache (sets synced_at, which is what get_items branch 3 serves offline).
• resume_queued_downloads resolves and pumps the pending download rows that were queued offline (they have stream_url IS NULL), mirroring the heal-and-pump pattern in player_preload_upcoming.

Structs

CatalogIndexEvent

Progress of a background index pass, for the staleness hint in the UI.

CatalogSyncResult

CatalogSyncStatus

IndexPassGuard 🔒

Clears INDEX_IN_PROGRESS however the pass leaves — including on the ? early return when get_libraries fails, which a plain store at the end of the function would leak.

ResumeQueuedResult

Constants

CATALOG_INDEX_EVENT

Kebab-case, per the project’s event convention.

CATALOG_INDEX_FIRST_CHECK 🔒

Delay before the first staleness check, to let sign-in complete and the repository be registered. Without it the first check runs against an empty repository manager and a fresh install would sit unindexed until the next tick.

CATALOG_INDEX_TICK 🔒

How often the scheduler wakes to check staleness. Far shorter than the TTL because a tick is nearly free — one indexed app_settings lookup — and it is what makes the indexer responsive to events it cannot subscribe to: signing in, and coming back online. The TTL, not the tick, decides whether a crawl actually happens.

CATALOG_INDEX_TTL 🔒

How long an index stays fresh before a re-index is due.

CATALOG_ITEM_TYPES 🔒

Item types worth caching for offline browsing: containers the library landing pages render plus the playable leaves users queue for download. MusicArtist and Playlist are here because search groups results by them (UR-060’s Artists group). Without them in the crawl, the local index can never answer an artist query and those groups can only ever be filled by the server leg. Keep this in step with what prune_stale_catalog is allowed to sweep — the crawl is only authoritative for the types it asks for.

LAST_CATALOG_SYNC_KEY 🔒

app_settings key holding the RFC-3339 timestamp of the last successful full-catalog sync.

VIDEO_ITEM_TYPES 🔒

Jellyfin item types whose download is a video stream rather than an audio one. The download queue stores an opaque media_type (‘audio’/‘video’); this is where the taxonomy that produces it lives, so the frontend never has to know which item types are video.

Statics

INDEX_IN_PROGRESS 🔒

Guards against two passes running at once. Replaces the frontend’s syncInProgress boolean in offlineCatalog.ts, which could not see a pass started by the scheduler.

Functions

catalog_sync_status

Report the last-synced timestamp so the UI can show a hint / decide whether to trigger a fresh sync.

index_is_due 🔒

Whether an index pass is due, given when one last completed.

maybe_run_scheduled_pass 🔒

One scheduler tick: check the preconditions, then index if due.

read_last_sync 🔒

Read the last-sync timestamp straight from app_settings.

requeue_mistyped_video_downloads 🔒

Requeue video downloads that were fetched as audio.

resolve_pending_download_urls 🔒

Core of resume_queued_downloads, factored out for testing: select every pending/stream_url IS NULL row, resolve each via resolve (returning None leaves the row pending), and heal the row so the pump can start it. The resolve closure receives (item_id, media_type, quality_preset).

resume_queued_downloads

Resolve the stream URL for every download row that was queued while offline (status = 'pending' AND stream_url IS NULL), then pump the queue so they start. Call this on reconnect.

run_index_pass 🔒

One full-catalog indexing pass, shared by the sync_full_catalog command and the background scheduler (DR-109) so there is exactly one implementation and one concurrency guard.

set_show_server_catalog

Control whether offline library queries reveal the full synced catalog (greyed-out, non-downloaded media) or only downloaded/local media.

spawn_catalog_indexer

Start the background catalog indexer.

sync_full_catalog

Walk every library on the server and persist all items to the offline cache so the full catalog is browsable offline (greyed out when not downloaded).