Skip to main content

## Module catalog

Source
Expand description

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).