Convert received playback items without copying wire ids
CI / check (pull_request) Successful in 2m18s
CI / check (pull_request) Successful in 2m18s
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:
1 parent
b8d8b532f2
commit
d2530dca6c
6 files changed
+169
-40
No files matched your search
+7
-5
@@ -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
@@ -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
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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"));
|
||||
|
||||
Reference in new issue
Block a user