Convert received playback items without copying wire ids

Add TrackItem::from_playback_track and PlaybackItem: a received podcast
episode becomes TrackItem::podcast_episode (sentinel ids) and a Jam
private placeholder gets no TrackItem, so the wire ids (0 for both) are
never copied. Narrow the TrackItem::key guidance: it is the source
identity, episodes must never be keyed by id, and content-first music
matching stays as it is. Document how TrackItem::podcast_episode differs
from the wire form.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-19 18:32:38 +02:00
1 parent b8d8b532f2
commit d2530dca6c
6 files changed
+169 -40

No files matched your search

+7 -5
View File
@@ -53,11 +53,13 @@ converges independently of delivery order. Migrations follow
`PRAGMA user_version`; the prototype podcast database is imported and its `PRAGMA user_version`; the prototype podcast database is imported and its
tables are kept as `legacy_*`; newer or foreign files are refused unchanged. tables are kept as `legacy_*`; newer or foreign files are refused unchanged.
`TrackItem.podcast` marks episode queue items, which music-only code must `TrackItem.podcast` marks episode queue items, which music-only code must
skip. Queue items are keyed by `TrackItem::key` (a typed `TrackItemKey`: skip. An episode queue item is identified by its episode id
library row, federated owner and item id, or episode id), never by the (`TrackItem::key`, a typed source identity: library row, federated owner and
numeric id: episodes use the fixed sentinel id, `release_id` and artist id item id, or episode id), never by the numeric id: episodes use the fixed
-1, which carries no identity and only keeps code written for library sentinel id, `release_id` and artist id -1, which carries no identity and
tracks (`id >= 0`) away from them. See the "SQLite reference store" section 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). of [PODCASTS.md](PODCASTS.md).
Filesystem scanning schedules, playback, federation lifecycle, and UI state Filesystem scanning schedules, playback, federation lifecycle, and UI state
+5 -2
View File
@@ -36,8 +36,11 @@
so existing `id < 0` / `release_id < 0` checks already treat them as so existing `id < 0` / `release_id < 0` checks already treat them as
non-library items; the sentinel carries no identity. New non-library items; the sentinel carries no identity. New
`TrackItem::key` / `TrackItemKey` (`lib:<id>`, `fed:<owner>:<item_id>`, `TrackItem::key` / `TrackItemKey` (`lib:<id>`, `fed:<owner>:<item_id>`,
`ep:<episode id>`): clients must key queue items by it, not by `id`. The `ep:<episode id>`), the source identity: episodes must be keyed by it (or
library database is unchanged. `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 - `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 item under several enclosure URLs, and the first refresh re-keys imported
GUID-less episodes without personal state to the ids the current feed GUID-less episodes without personal state to the ids the current feed
+18 -5
View File
@@ -634,11 +634,24 @@ must keep the same invariants.
decoded; it only keeps music-only code that predates podcasts decoded; it only keeps music-only code that predates podcasts
(`id >= 0`, `release_id < 0` checks) from taking an episode for library (`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. 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:<id>`,
`TrackItem::key` (a typed `TrackItemKey`; string form `lib:<id>`, `fed:<owner>:<item_id>`, `ep:<episode id>`) is the source identity of a
`fed:<owner>:<item_id>`, `ep:<episode id>`), and on the wire by queue item; on the wire it is `PlaybackSource`. An episode is identified
`PlaybackSource`, never by the numeric id. Keying by id (for example a by `TrackItem.podcast` / `ep:` only and must never be keyed by its numeric
`local:{id}` string) would merge all episodes into one. 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 ## Versioning
+12 -6
View File
@@ -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 content ids, federation downloads) must check `TrackItem::is_podcast`; the
music library never stores episodes. music library never stores episodes.
Key queue items, the current track and position matching by `TrackItem::key` returns the typed source identity of a queue item
`TrackItem::key`, which returns a typed `TrackItemKey` (`lib:<id>`, (`TrackItemKey`: `lib:<id>`, `fed:<owner>:<item_id>` or `ep:<episode id>` as
`fed:<owner>:<item_id>` or `ep:<episode id>` as a string), not by a string). A negative `TrackItem::id` only means "not a library row". Every
`TrackItem::id`: a negative id only means "not a library row". Every podcast podcast item has the same sentinel `id`, `release_id` and artist id
item has the same sentinel `id`, `release_id` and artist id
(`TrackItem::NOT_A_LIBRARY_ROW` = -1). It carries no identity and must not (`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 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 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.
+2 -2
View File
@@ -26,8 +26,8 @@ use rusqlite::{Connection, OptionalExtension as _, params};
pub use models::{ pub use models::{
ArtistCard, ArtistDetail, ArtistRef, ArtistsPage, Availability, FederatedTrack, LibraryFilters, ArtistCard, ArtistDetail, ArtistRef, ArtistsPage, Availability, FederatedTrack, LibraryFilters,
LibrarySourceMode, PlaylistCard, PlaylistDetail, ReleaseCard, ReleaseDetail, ReleaseEdit, LibrarySourceMode, PlaybackItem, PlaylistCard, PlaylistDetail, ReleaseCard, ReleaseDetail,
SearchResults, TrackEdit, TrackItem, TrackItemKey, ReleaseEdit, SearchResults, TrackEdit, TrackItem, TrackItemKey,
}; };
/// The virtual "Liked tracks" playlist id, kept from the server API. /// The virtual "Liked tracks" playlist id, kept from the server API.
+125 -20
View File
@@ -1,6 +1,7 @@
//! Data shapes the views render. They mirror what the furumusic API used to //! 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. //! 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 music_dht::podcast::{EpisodeId, PodcastEpisodeRef};
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
@@ -142,14 +143,20 @@ pub struct ArtistRef {
/// ///
/// A negative `id` therefore means "not a library row" and nothing else: it /// 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 /// carries no identity and must never be decoded, compared across items or
/// used as a key. Clients key queue items, current-track and position /// used as a key. The -1 sentinel only keeps music-only code that predates
/// matching by [`TrackItem::key`] (or, on the wire, by /// podcasts (`id >= 0` / `release_id < 0` checks) from treating an episode
/// `music_dht::device_sync::PlaybackSource`), not by `id`. The -1 sentinel /// as library track, release or artist 0.
/// only keeps music-only code that predates podcasts (`id >= 0` / ///
/// `release_id < 0` checks) from treating an episode as library track, /// [`TrackItem::key`] is the *source* identity. It does not merge a pending
/// release or artist 0; code that keys items by `id` (for example a /// federated item with its imported library copy, which share a content id
/// `local:{id}` string) would still merge all episodes and must switch to /// but have different keys (`fed:` and `lib:`). Clients that key playback
/// [`TrackItem::key`]. /// 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 /// # Podcast episodes
/// ///
@@ -198,12 +205,14 @@ pub struct TrackItem {
pub podcast: Option<PodcastEpisodeRef>, pub podcast: Option<PodcastEpisodeRef>,
} }
/// 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 /// Two items with equal keys are the same track or episode; the same track
/// position matching instead of [`TrackItem::id`], which identifies library /// may still appear more than once in a queue. The key has no content-id
/// rows only. Two items with equal keys are the same track or episode; the /// equivalence: a pending federated item and its library copy differ. Use it
/// same track may still appear more than once in a queue. /// 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 /// The [`Display`](std::fmt::Display) form is stable and suitable as a map
/// key or in logs: /// key or in logs:
@@ -234,6 +243,21 @@ pub enum TrackItemKey {
Transient(i64), 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<TrackItem>),
/// 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 { impl std::fmt::Display for TrackItemKey {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self { match self {
@@ -277,15 +301,20 @@ impl TrackItem {
/// Queue item for a podcast episode streamed from the publisher. /// 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 /// `music_dht::device_sync` (the episode title, the podcast title as
/// artist and release, the announced duration; no track or disc number) /// artist and release, the announced duration; no track or disc number).
/// and add the publication year. Season and episode number stay in the /// The other fields differ from that wire form on purpose:
/// reference.
/// ///
/// `id`, `release_id` and the artist id are the sentinel /// * `id`, `release_id` and the artist id are the sentinel
/// [`TrackItem::NOT_A_LIBRARY_ROW`] for every episode: the item's identity /// [`TrackItem::NOT_A_LIBRARY_ROW`] (-1) for every episode, where the
/// is [`TrackItem::podcast`] alone ([`TrackItem::key`]). /// 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 { pub fn podcast_episode(episode: PodcastEpisodeRef) -> Self {
Self { Self {
id: Self::NOT_A_LIBRARY_ROW, 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). /// Whether this item is a podcast episode (not music).
pub fn is_podcast(&self) -> bool { pub fn is_podcast(&self) -> bool {
self.podcast.is_some() self.podcast.is_some()
@@ -681,6 +736,56 @@ mod tests {
assert_ne!(pending_minus_one.key(), track.key()); 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] #[test]
fn episodes_share_the_sentinel_id_but_not_the_key() { fn episodes_share_the_sentinel_id_but_not_the_key() {
let first = TrackItem::podcast_episode(episode_ref("e1")); let first = TrackItem::podcast_episode(episode_ref("e1"));