diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 27206c5..0553b05 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -53,11 +53,13 @@ converges independently of delivery order. Migrations follow `PRAGMA user_version`; the prototype podcast database is imported and its tables are kept as `legacy_*`; newer or foreign files are refused unchanged. `TrackItem.podcast` marks episode queue items, which music-only code must -skip. Queue items are keyed by `TrackItem::key` (a typed `TrackItemKey`: -library row, federated owner and item id, or episode id), never by the -numeric id: episodes use the fixed sentinel id, `release_id` and artist id --1, which carries no identity and only keeps code written for library -tracks (`id >= 0`) away from them. See the "SQLite reference store" section +skip. An episode queue item is identified by its episode id +(`TrackItem::key`, a typed source identity: library row, federated owner and +item id, or episode id), never by the numeric id: episodes use the fixed +sentinel id, `release_id` and artist id -1, which carries no identity and +only keeps code written for library tracks (`id >= 0`) away from them. +Received playback items are converted with `TrackItem::from_playback_track`, +which never copies the wire ids (0 for episodes and private placeholders). See the "SQLite reference store" section of [PODCASTS.md](PODCASTS.md). Filesystem scanning schedules, playback, federation lifecycle, and UI state diff --git a/CHANGELOG.md b/CHANGELOG.md index 876dc07..0f9f284 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,8 +36,11 @@ so existing `id < 0` / `release_id < 0` checks already treat them as non-library items; the sentinel carries no identity. New `TrackItem::key` / `TrackItemKey` (`lib:`, `fed::`, - `ep:`): clients must key queue items by it, not by `id`. The - library database is unchanged. + `ep:`), the source identity: episodes must be keyed by it (or + `TrackItem.podcast`), never by `id`; content-first music matching stays + as it is. New `TrackItem::from_playback_track` / `PlaybackItem` convert + received playback items without copying wire ids (0 for episodes and Jam + private placeholders). The library database is unchanged. - `furumi-library 0.3.0`: prototype import collapses rows of one GUID-less item under several enclosure URLs, and the first refresh re-keys imported GUID-less episodes without personal state to the ids the current feed diff --git a/PODCASTS.md b/PODCASTS.md index 632cec8..010a50d 100644 --- a/PODCASTS.md +++ b/PODCASTS.md @@ -634,11 +634,24 @@ must keep the same invariants. decoded; it only keeps music-only code that predates podcasts (`id >= 0`, `release_id < 0` checks) from taking an episode for library track, release or artist 0. There is no reserved range of negative ids. -* Clients key queue items, the current track and position matching by - `TrackItem::key` (a typed `TrackItemKey`; string form `lib:`, - `fed::`, `ep:`), and on the wire by - `PlaybackSource`, never by the numeric id. Keying by id (for example a - `local:{id}` string) would merge all episodes into one. +* `TrackItem::key` (a typed `TrackItemKey`; string form `lib:`, + `fed::`, `ep:`) is the source identity of a + queue item; on the wire it is `PlaybackSource`. An episode is identified + by `TrackItem.podcast` / `ep:` only and must never be keyed by its numeric + id: keying by id (for example a `local:{id}` string) would merge all + episodes into one. `TrackItemKey` has no content-id equivalence (a pending + federated item and its imported library copy differ), so clients that + match music content-first keep doing that and add the podcast branch + before any fallback to the id. +* Wire ids of podcast items and of Jam private placeholders are `0` + (`PlaybackTrack::podcast_episode`, `PlaybackTrack::private_placeholder`) + and must not be copied into a `TrackItem`. + `TrackItem::from_playback_track` classifies a received item as + `PlaybackItem::Music` (the client's music path), `PodcastEpisode` (built + with `TrackItem::podcast_episode`, sentinel ids) or `Private` (not + playable, no `TrackItem`). Besides the ids, `TrackItem::podcast_episode` + also differs from the wire form in `release_year` (publication year) and + `audio_format` (`None`; the MIME type stays in the reference). ## Versioning diff --git a/crates/furumi-library/README.md b/crates/furumi-library/README.md index 5a752b3..6ad2aaa 100644 --- a/crates/furumi-library/README.md +++ b/crates/furumi-library/README.md @@ -66,12 +66,18 @@ The store is synchronous: methods take `&self` and lock one connection, so content ids, federation downloads) must check `TrackItem::is_podcast`; the music library never stores episodes. -Key queue items, the current track and position matching by -`TrackItem::key`, which returns a typed `TrackItemKey` (`lib:`, -`fed::` or `ep:` as a string), not by -`TrackItem::id`: a negative id only means "not a library row". Every podcast -item has the same sentinel `id`, `release_id` and artist id +`TrackItem::key` returns the typed source identity of a queue item +(`TrackItemKey`: `lib:`, `fed::` or `ep:` as +a string). A negative `TrackItem::id` only means "not a library row". Every +podcast item has the same sentinel `id`, `release_id` and artist id (`TrackItem::NOT_A_LIBRARY_ROW` = -1). It carries no identity and must not be decoded; it only keeps music-only code that predates podcasts from taking an episode for library track, release or artist 0. The episode's identity is -`TrackItem.podcast` alone. +`TrackItem.podcast` alone, so queue, current-track and position matching +must check it before any fallback to the id. `TrackItemKey` does not equate +a pending federated item with its library copy; clients that match music by +content id keep doing so. + +Convert received `PlaybackTrack`s with `TrackItem::from_playback_track` +(`PlaybackItem::Music`, `PodcastEpisode` or `Private`): podcast items and +Jam private placeholders carry id 0 on the wire, which must never be copied. diff --git a/crates/furumi-library/src/lib.rs b/crates/furumi-library/src/lib.rs index 405371a..e776d0a 100644 --- a/crates/furumi-library/src/lib.rs +++ b/crates/furumi-library/src/lib.rs @@ -26,8 +26,8 @@ use rusqlite::{Connection, OptionalExtension as _, params}; pub use models::{ ArtistCard, ArtistDetail, ArtistRef, ArtistsPage, Availability, FederatedTrack, LibraryFilters, - LibrarySourceMode, PlaylistCard, PlaylistDetail, ReleaseCard, ReleaseDetail, ReleaseEdit, - SearchResults, TrackEdit, TrackItem, TrackItemKey, + LibrarySourceMode, PlaybackItem, PlaylistCard, PlaylistDetail, ReleaseCard, ReleaseDetail, + ReleaseEdit, SearchResults, TrackEdit, TrackItem, TrackItemKey, }; /// The virtual "Liked tracks" playlist id, kept from the server API. diff --git a/crates/furumi-library/src/models.rs b/crates/furumi-library/src/models.rs index 8458632..96a3fea 100644 --- a/crates/furumi-library/src/models.rs +++ b/crates/furumi-library/src/models.rs @@ -1,6 +1,7 @@ //! Data shapes the views render. They mirror what the furumusic API used to //! return, but every field is now filled from the local SQLite library. +use music_dht::device_sync::{PlaybackSource, PlaybackTrack}; use music_dht::podcast::{EpisodeId, PodcastEpisodeRef}; use serde::{Deserialize, Serialize}; @@ -142,14 +143,20 @@ pub struct ArtistRef { /// /// A negative `id` therefore means "not a library row" and nothing else: it /// carries no identity and must never be decoded, compared across items or -/// used as a key. Clients key queue items, current-track and position -/// matching by [`TrackItem::key`] (or, on the wire, by -/// `music_dht::device_sync::PlaybackSource`), not by `id`. The -1 sentinel -/// only keeps music-only code that predates podcasts (`id >= 0` / -/// `release_id < 0` checks) from treating an episode as library track, -/// release or artist 0; code that keys items by `id` (for example a -/// `local:{id}` string) would still merge all episodes and must switch to -/// [`TrackItem::key`]. +/// used as a key. The -1 sentinel only keeps music-only code that predates +/// podcasts (`id >= 0` / `release_id < 0` checks) from treating an episode +/// as library track, release or artist 0. +/// +/// [`TrackItem::key`] is the *source* identity. It does not merge a pending +/// federated item with its imported library copy, which share a content id +/// but have different keys (`fed:` and `lib:`). Clients that key playback +/// items content-first (content id, then federated source, then id) keep +/// doing so for music; what they must add is a podcast branch +/// ([`TrackItem::podcast`], or [`TrackItemKey::PodcastEpisode`]) checked +/// before any fallback to `id`. An episode must never be keyed by `id`: a +/// `local:{id}` key would merge all episodes into one. On the wire the item +/// kind is `music_dht::device_sync::PlaybackSource`; convert received items +/// with [`TrackItem::from_playback_track`], never by copying wire ids. /// /// # Podcast episodes /// @@ -198,12 +205,14 @@ pub struct TrackItem { pub podcast: Option, } -/// Typed identity of a [`TrackItem`], from [`TrackItem::key`]. +/// Typed source identity of a [`TrackItem`], from [`TrackItem::key`]. /// -/// Use it (or its string form) to key queue items, the current track and -/// position matching instead of [`TrackItem::id`], which identifies library -/// rows only. Two items with equal keys are the same track or episode; the -/// same track may still appear more than once in a queue. +/// Two items with equal keys are the same track or episode; the same track +/// may still appear more than once in a queue. The key has no content-id +/// equivalence: a pending federated item and its library copy differ. Use it +/// where the source matters (and always for podcast episodes, which have no +/// other identity); code that matches music by content id keeps doing that +/// and checks the podcast variant first (see [`TrackItem`]). /// /// The [`Display`](std::fmt::Display) form is stable and suitable as a map /// key or in logs: @@ -234,6 +243,21 @@ pub enum TrackItemKey { Transient(i64), } +/// What a received `music_dht::device_sync::PlaybackTrack` is locally, from +/// [`TrackItem::from_playback_track`]. +#[derive(Debug, Clone)] +pub enum PlaybackItem { + /// A music track. Convert it with the client's music path (content id, + /// then federated source); its wire ids are the sender's. + Music, + /// A podcast episode, built with [`TrackItem::podcast_episode`]. + PodcastEpisode(Box), + /// A Jam private placeholder: not playable and without identity. Show it + /// as `music_dht::device_sync::PRIVATE_ITEM_TITLE` where the queue is + /// displayed; never insert it as a library or queue track, never key it. + Private, +} + impl std::fmt::Display for TrackItemKey { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { match self { @@ -277,15 +301,20 @@ impl TrackItem { /// Queue item for a podcast episode streamed from the publisher. /// - /// Display fields mirror `PlaybackTrack::podcast_episode` of + /// Title, artist and release follow `PlaybackTrack::podcast_episode` of /// `music_dht::device_sync` (the episode title, the podcast title as - /// artist and release, the announced duration; no track or disc number) - /// and add the publication year. Season and episode number stay in the - /// reference. + /// artist and release, the announced duration; no track or disc number). + /// The other fields differ from that wire form on purpose: /// - /// `id`, `release_id` and the artist id are the sentinel - /// [`TrackItem::NOT_A_LIBRARY_ROW`] for every episode: the item's identity - /// is [`TrackItem::podcast`] alone ([`TrackItem::key`]). + /// * `id`, `release_id` and the artist id are the sentinel + /// [`TrackItem::NOT_A_LIBRARY_ROW`] (-1) for every episode, where the + /// wire form carries `0`; the item's identity is [`TrackItem::podcast`] + /// alone ([`TrackItem::key`]); + /// * `release_year` is the publication year (`None` on the wire); + /// * `audio_format` is `None` (the wire form carries the MIME type, which + /// stays in the reference). + /// + /// Season and episode number stay in the reference. pub fn podcast_episode(episode: PodcastEpisodeRef) -> Self { Self { id: Self::NOT_A_LIBRARY_ROW, @@ -317,6 +346,32 @@ impl TrackItem { } } + /// Classifies a received `music_dht::device_sync::PlaybackTrack` and + /// builds the local queue item for non-music sources. + /// + /// The wire `id` and `release_id` of podcast episodes and of Jam private + /// placeholders are `0`, and those of music items are the sender's local + /// ids. None of them identifies anything on this device, so they are + /// never copied: + /// + /// * a podcast episode becomes [`TrackItem::podcast_episode`] of its + /// [`PlaybackSource::PodcastEpisode`] reference (sentinel ids, key + /// `ep:`), whatever the legacy display fields say; + /// * a private placeholder ([`PlaybackSource::Private`]) is not playable + /// and has no identity, so no `TrackItem` exists for it; + /// * music (no source, or [`PlaybackSource::Music`]) is left to the + /// client's music path, which resolves it by content id or federated + /// source. + pub fn from_playback_track(track: &PlaybackTrack) -> PlaybackItem { + match &track.source { + None | Some(PlaybackSource::Music) => PlaybackItem::Music, + Some(PlaybackSource::PodcastEpisode(episode)) => PlaybackItem::PodcastEpisode( + Box::new(Self::podcast_episode(episode.as_ref().clone())), + ), + Some(PlaybackSource::Private) => PlaybackItem::Private, + } + } + /// Whether this item is a podcast episode (not music). pub fn is_podcast(&self) -> bool { self.podcast.is_some() @@ -681,6 +736,56 @@ mod tests { assert_ne!(pending_minus_one.key(), track.key()); } + #[test] + fn received_playback_tracks_never_copy_wire_ids() { + // F1 wire form of an episode: id 0, release_id 0. + let episode = episode_ref("e1"); + let wire = PlaybackTrack::podcast_episode(episode.clone()); + assert_eq!((wire.id, wire.release_id), (0, 0)); + let PlaybackItem::PodcastEpisode(item) = TrackItem::from_playback_track(&wire) else { + panic!("an episode is not music"); + }; + assert_eq!(item.id, TrackItem::NOT_A_LIBRARY_ROW); + assert_eq!(item.release_id, TrackItem::NOT_A_LIBRARY_ROW); + assert!(item.artists.iter().all(|artist| artist.id < 0)); + assert_eq!( + item.key(), + TrackItemKey::PodcastEpisode(episode.episode_id.clone()) + ); + assert_eq!(item.podcast_episode_ref(), Some(&episode)); + // Legacy display fields an older sender filled in do not matter. + let mut odd = wire.clone(); + odd.id = 42; + odd.release_id = 7; + odd.title = "Something else".into(); + let PlaybackItem::PodcastEpisode(odd) = TrackItem::from_playback_track(&odd) else { + panic!("the source decides"); + }; + assert_eq!(odd.key(), item.key()); + assert_eq!(odd.id, TrackItem::NOT_A_LIBRARY_ROW); + + // A private placeholder (also id 0) never becomes library row 0. + let private = PlaybackTrack::private_placeholder(); + assert_eq!(private.id, 0); + assert!(matches!( + TrackItem::from_playback_track(&private), + PlaybackItem::Private + )); + + // Music is left to the client's music path. + let mut music = wire; + music.source = None; + assert!(matches!( + TrackItem::from_playback_track(&music), + PlaybackItem::Music + )); + music.source = Some(PlaybackSource::Music); + assert!(matches!( + TrackItem::from_playback_track(&music), + PlaybackItem::Music + )); + } + #[test] fn episodes_share_the_sentinel_id_but_not_the_key() { let first = TrackItem::podcast_episode(episode_ref("e1"));