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
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
+5 -2
View File
@@ -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:<id>`, `fed:<owner>:<item_id>`,
`ep:<episode id>`): clients must key queue items by it, not by `id`. The
library database is unchanged.
`ep:<episode id>`), 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
+18 -5
View File
@@ -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:<id>`,
`fed:<owner>:<item_id>`, `ep:<episode id>`), 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:<id>`,
`fed:<owner>:<item_id>`, `ep:<episode id>`) 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
+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
music library never stores episodes.
Key queue items, the current track and position matching by
`TrackItem::key`, which returns a typed `TrackItemKey` (`lib:<id>`,
`fed:<owner>:<item_id>` or `ep:<episode id>` 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:<id>`, `fed:<owner>:<item_id>` or `ep:<episode id>` 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.
+2 -2
View File
@@ -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.
+125 -20
View File
@@ -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<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
/// 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<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 {
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"));