Files
qbz/crates/qbz-source/src/error.rs
T
vicrodh f1b4241342 feat(source): add qbz-source, the source-agnostic media seam
Stage 1 of the seam the owner asked for: "son vistas súper híbridas donde se
mezcla Qobuz/Local(Folders/Plex) ... hay que hacer una solución agnóstica
porque no tardamos en meter a Jellyfin y quizás Navidrome". Nothing is wired
yet — this lands the crate, its three source implementations and its tests.
`qbz-qt` and `qbz` are untouched, so this commit changes no behaviour.

The problem it exists to end, measured rather than assumed: 129 source-branching
sites across 30 files in qbz-qt alone, SEVEN distinct item->tracks resolvers
none of which can reach the others, FIVE non-interchangeable artwork pipelines
over one correct taxonomy, and six incompatible source vocabularies — three of
which cannot express Plex at all, including the PERSISTED one (`AlbumSource` is
`Qobuz|Local`). Every hybrid view re-wires the per-source handling by hand,
which is why something is always missing.

One `Source` trait covering the four concerns together — tracks, metadata and
origin, artwork, playback — because splitting them is exactly what lets a view
forget one. A `SourceRegistry` with claim-priority ordering (Qobuz, Plex, then
Local; Plex-before-Local is load-bearing). `RegistryResolver` implements
`qbz_mixtape::ItemResolver`, so that crate and the Slint glue stay byte-
untouched and keep compiling.

The three measured bugs die structurally, not by discipline:
- The local DB was reopened PER CALL, so a My QBZ collection logged one
  "Opening library database" per item (34 measured live). `LocalSource` owns a
  pooled handle, and it hands out no guard — only `with(|db| ...)` — so a
  `!Send` `&LibraryDatabase` provably cannot cross an await. `qbz-mixtape`'s
  sync-resolver constraint becomes an API property instead of a comment.
- A `plex:<hash>` album key reached an API that wants a rating key. `MediaRef`
  has no public constructor: only `registry.claim` mints one, and
  `PlexSource::claim` rejects that shape in track position. The survey also
  found a second, undiscovered face of the same bug — "Go to album" on a Plex
  track row opens an empty page.
- Local rows in a hybrid list rendered placeholder discs. Traced to its real
  mechanism: those items are stored with `artwork_url: None` and the only
  backfill is behind a Qobuz-client gate, so offline or pre-login the art is on
  disk and never shown. `Source::artwork` is one call per row whatever the
  source, and keeps the cheap/cold split the local path already had.

Adding Jellyfin is one new file, four diff lines inside this crate, and one
line in `auth_qt.rs` — and the design states this only holds BECAUSE artwork
sits on the trait.

36 tests. The id tests derive their fixtures from `PLEX_TRACK_ID_FLOOR` instead
of transcribing them, which is not pedantry: the survey's own id table — the
artefact meant to be the definitive reference — paired a namespaced id with the
wrong rating key, and the transcribed test caught it on the first run.

Design and adversarial review (6 BLOCKER / 10 MAJOR / 7 MINOR, all corrected):
qbz-nix-docs/qt-frontend/2026-07-30-source-seam/.

cc
2026-07-30 16:14:30 -06:00

83 lines
3.4 KiB
Rust

//! The one error vocabulary for the seam.
//!
//! Note the field is `by`, never `source`: `thiserror` (workspace pins `= "2"`,
//! `crates/Cargo.toml:75`) treats a variant field NAMED `source` as the
//! `std::error::Error::source()` chain and requires it to implement `Error`.
//! [`crate::SourceId`] is a `&'static str` newtype and does not, so a field
//! called `source` here would not compile.
use crate::id::{ItemKind, RawRef, SourceId};
/// Everything that can go wrong between "a caller has a string" and "the
/// frontend has tracks, metadata, artwork or a playback ticket".
#[derive(Debug, thiserror::Error)]
pub enum SourceError {
/// No source recognised the reference at all.
#[error("no source claims {0:?}")]
Unclaimed(RawRef),
/// A bare id that MORE THAN ONE source could legitimately own, with no
/// source word to break the tie (survey §6.3: a numeric id can be a Qobuz
/// track id, `local_tracks.id = 2954`, OR a Plex rating key `44440`).
///
/// The registry REFUSES to guess. This is deliberately loud: it turns the
/// producer-side gaps (`HomeCard` has no `source` field — survey IC-7; the
/// eight QML sites that hardcode `"source": "qobuz"` — survey §2.6) into
/// visible failures instead of silently mis-rendered rows.
#[error("ambiguous id {id:?} ({kind:?}): candidates {candidates:?}; caller must supply a source")]
Ambiguous {
id: String,
kind: Option<ItemKind>,
candidates: Vec<SourceId>,
},
/// The named home for what bug 2 used to be. A source that RECOGNISES a
/// shape but rejects it in this position says so LOUDLY here, instead of
/// forwarding it to an API that answers 404 two layers down.
#[error("{by}: id shape rejected: {id} ({why})")]
BadIdShape {
by: SourceId,
id: String,
why: &'static str,
},
/// The source exists but has nothing to work with (no Qobuz client, no
/// Plex credentials, no bound user directory).
#[error("{by}: not configured ({why})")]
NotConfigured { by: SourceId, why: &'static str },
/// The reference is well-formed and owned, and the thing is not there.
/// A zero-track resolve is this, with the item's id — there is deliberately
/// no separate `Empty` variant (two variants for one condition is how the
/// six vocabularies in survey §1 multiplied in the first place).
#[error("{by}: {kind:?} {id} not found")]
NotFound {
by: SourceId,
kind: ItemKind,
id: String,
},
/// This source does not resolve that kind. Carries `qbz-mixtape`'s "local
/// playlists not supported in this release" contract (enqueue.rs:418-423).
#[error("{by}: {kind:?} is not supported")]
Unsupported { by: SourceId, kind: ItemKind },
/// Anything the underlying crate reported as a string.
#[error("{by}: {msg}")]
Backend { by: SourceId, msg: String },
}
impl SourceError {
/// Which source produced this error, when one did.
pub fn by(&self) -> Option<SourceId> {
match self {
SourceError::Unclaimed(_) | SourceError::Ambiguous { .. } => None,
SourceError::BadIdShape { by, .. }
| SourceError::NotConfigured { by, .. }
| SourceError::NotFound { by, .. }
| SourceError::Unsupported { by, .. }
| SourceError::Backend { by, .. } => Some(*by),
}
}
}