diff --git a/AGENTS.md b/AGENTS.md index 3e2cf2d..48fe0cb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -173,7 +173,9 @@ When changing it: go only to v4 peers (`op_allowed_for_peer`, `SyncSnapshot::for_peer`, `playback_allowed_for_peer`), a podcast queue is never handed to an older device and its playback commands are ignored while the queue has episodes; - never strip episodes from a queue to make it fit an old peer; + never strip episodes from a queue to make it fit an old peer; an older + peer still gets the playback coordination, with the queue redacted + (`redact_for_jam`), so its engine does not fail over; - apply podcast operations and snapshot sections only through `PodcastStore` (`apply_remote_op`, `apply_snapshot`); never call the podcast store while holding the sync-log connection; diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 5819e04..7be974e 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -242,7 +242,14 @@ travels as `PlaybackSource::PodcastEpisode` with the reference needed to play it (the receiving device streams it from the publisher at the handed-off position, with or without a subscription). A queue with episodes is not handed to a device below protocol v4, and playback commands from such a device are -ignored while the local queue has episodes. +ignored while the local queue has episodes. Such a device still gets the +playback snapshot with its coordination envelope, but with every episode +replaced by an opaque "Private item" (`redact_for_jam`): an engine renews the +owner's liveness only from the owner's own announcements, so an old device +that heard nothing would take over by automatic failover after +`owner_timeout_ms` and replace the queue. This departs from FRID's +`PLAYBACK_PROTOCOL.md` rule 1 ("otherwise send `None`") and is reported to +FRID as a contract gap. Active-device leases and idle timing prevent stale snapshots from immediately taking control after a device reconnects. This provides practical coordination diff --git a/CHANGELOG.md b/CHANGELOG.md index 68bfcdd..b4d6356 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -53,7 +53,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 byte (golden tests). Devices below protocol 4 never receive podcast operations, podcast snapshot sections or a queue with episodes: handing such a queue to them is refused ("needs a Furumi update"), and their - playback commands are ignored while the queue has episodes. + playback commands are ignored while the queue has episodes. They still get + the playback coordination, with each episode shown as "Private item", so + they do not take playback over after two minutes of silence. - Jam guests see the host's podcast episodes as "Private item" (no title, feed or address). Guest changes that add, drop or duplicate them, or seek in them, are refused; a guest leaving a Jam drops the placeholders. diff --git a/README.md b/README.md index ef06887..d67a175 100644 --- a/README.md +++ b/README.md @@ -251,7 +251,12 @@ Podcasts and your connected devices: playing, even if that device is not subscribed. Devices that run an older Furumi (device sync before v4) cannot keep episodes: handing such a queue to them is refused with "needs a Furumi update", their remote control is - ignored while the queue has episodes, and they get no podcast data. + ignored while the queue has episodes, and they get no podcast data: they + see such a queue with "Private item" in place of each episode, so they + keep seeing this device as the playing one. An older device still takes + over when you choose it as the output (Play on it) or when it starts while + this device is paused (`take_paused_on_startup`); this device then shows + that device's queue, without the episodes (their saved positions stay). - **Audio from the publisher.** Every device streams the episode from the publisher's server itself. Furumi peers never pass podcast audio to each other, and nothing is kept after playback. diff --git a/src/devices.rs b/src/devices.rs index f6f7d5c..56e52a2 100644 --- a/src/devices.rs +++ b/src/devices.rs @@ -11,7 +11,8 @@ //! and are relayed; podcast snapshot sections are exported from and merged //! into that store. Everything sent to a peer is gated by the version that //! peer reported itself (`op_allowed_for_peer`, `SyncSnapshot::for_peer`, -//! `playback_allowed_for_peer`). +//! `playback_allowed_for_peer`; a queue with podcast items reaches an older +//! peer only redacted, for its ownership engine). use music_dht::playback::{Checkpoint, CommandStamp, Config as PlaybackConfig, Engine}; use std::collections::{BTreeMap, BTreeSet}; @@ -147,7 +148,9 @@ struct PodcastLink { /// /// A podcast episode travels with its explicit source /// (`PlaybackSource::PodcastEpisode`), never as a music item. Peers below -/// protocol v4 do not get such a queue at all (`playback_allowed_for_peer`). +/// protocol v4 never get the episodes (`playback_allowed_for_peer`): they +/// see the queue redacted to "Private item" placeholders, only so that their +/// ownership engine keeps hearing from the owner. pub trait PlaybackTrackExt { /// Wire form of a queue item. Device-local paths are never sent. fn from_track(track: &TrackItem) -> Self; @@ -2985,10 +2988,6 @@ impl DeviceSync { } } - /// The playback snapshot for a peer, or `None` when the queue has - /// podcast items and the peer is below v4 (`playback_allowed_for_peer`). - /// Episodes are never stripped to make the state fit: an old client - /// would forward the shortened queue and lose them for every device. /// Refuses to hand a queue with podcast items to a device below v4 /// ("that device needs an update"), before ownership changes. pub fn ensure_playback_supported_by( @@ -3022,10 +3021,27 @@ impl DeviceSync { .unwrap_or_else(|| short_id(device_id)) } + /// The playback snapshot for a peer. + /// + /// A peer below v4 cannot carry a queue with podcast items + /// (`playback_allowed_for_peer`), but it still needs the coordination + /// envelope: an engine renews the owner's liveness only from the + /// owner's own announcements, so an old device that hears nothing takes + /// playback over by automatic failover after `owner_timeout_ms` (two + /// minutes by default) and this device would then adopt its queue, + /// losing the episodes. Such a peer therefore gets the announcement with + /// the queue redacted like for Jam (`redact_for_jam`: every episode + /// becomes an opaque "Private item", order and transport kept). The + /// episodes are never stripped, and the commands the peer derives from + /// that state are refused (`playback_command_allowed_from_peer`). + /// FRID's PLAYBACK_PROTOCOL.md rule 1 still says "send `None`"; this is + /// reported as a contract gap. fn local_playback_snapshot_for(&self, peer_version: u16) -> Option { - lock(&self.playback).local.clone().filter(|snapshot| { - music_dht::device_sync::playback_allowed_for_peer(&snapshot.state, peer_version) - }) + let mut snapshot = lock(&self.playback).local.clone()?; + if !music_dht::device_sync::playback_allowed_for_peer(&snapshot.state, peer_version) { + snapshot.state = music_dht::device_sync::redact_for_jam(snapshot.state); + } + Some(snapshot) } fn apply_playback_snapshot(&self, sender: &str, snapshot: PlaybackSnapshot) -> Result<()> { diff --git a/src/devices/podcast_sync_tests.rs b/src/devices/podcast_sync_tests.rs index ece65f8..e10f386 100644 --- a/src/devices/podcast_sync_tests.rs +++ b/src/devices/podcast_sync_tests.rs @@ -543,9 +543,20 @@ fn a_v3_peer_gets_no_podcast_state_and_catches_up_from_the_snapshot_after_upgrad panic!("expected a hello"); }; assert!(!json.contains("podcast"), "{json}"); + assert!(!json.contains(&episode.audio_url), "{json}"); assert_eq!(ops.len(), 1, "only the like: {ops:?}"); assert_eq!(snapshot.likes.len(), 1); - assert!(playback.is_none()); + // The playback snapshot comes for its coordination, with the episode + // redacted to an opaque placeholder. + let playback = playback.expect("coordination for the old engine"); + assert!(playback.coordination.is_some()); + assert_eq!(playback.state.queue.len(), 1); + assert_eq!( + playback.state.queue[0].title, + music_dht::device_sync::PRIVATE_ITEM_TITLE + ); + assert_eq!(playback.state.queue[0].id, 0); + assert_eq!(playback.state.position_secs, 300.0); // The old peer acknowledges everything it was sent. a.sync.note_peer_vector(&old.id, &vector).unwrap(); @@ -699,9 +710,8 @@ fn a_handoff_between_v4_devices_carries_the_episode_and_its_position() { assert!(!items[1].is_podcast()); } -#[test] -fn a_podcast_queue_is_not_handed_to_or_replaced_by_a_v3_device() { - let mut a = device(); +/// Trusts `dev_old`, a furumi-tui 0.3.x device ("Old laptop", sync v3). +fn trust_old_device(a: &Device) { a.sync.apply_device_trusted("dev_old", 1).unwrap(); a.sync .apply_device_profile( @@ -720,6 +730,12 @@ fn a_podcast_queue_is_not_handed_to_or_replaced_by_a_v3_device() { VersionReport::SelfReported(Some(3)), ) .unwrap(); +} + +#[test] +fn a_podcast_queue_is_not_handed_to_or_replaced_by_a_v3_device() { + let mut a = device(); + trust_old_device(&a); let with_episode = state_with( vec![music_wire(), PlaybackTrack::podcast_episode(episode_ref(7))], 12.0, @@ -787,6 +803,94 @@ fn a_podcast_queue_is_not_handed_to_or_replaced_by_a_v3_device() { ); } +/// A 0.3.x device runs the shared engine with the default configuration: +/// automatic failover once the owner has not been heard from for +/// `owner_timeout_ms`. While this device owns a queue with an episode, the +/// old device must keep hearing from it (redacted queue, real coordination) +/// so that it never takes over by itself and replaces the queue. +#[test] +fn an_old_device_keeps_hearing_from_a_podcast_queue_owner_and_never_fails_over() { + use super::wire_compat_tests::legacy; + + let a = device(); + trust_old_device(&a); + a.sync.claim_playback(&a.id).unwrap(); + let episode = episode_ref(8); + let mut state = state_with( + vec![ + music_wire(), + PlaybackTrack::podcast_episode(episode.clone()), + ], + 12.0, + ); + state.queue_pos = 1; + state.paused = false; + + let config = PlaybackConfig::default(); + assert!(config.automatic_failover); + let start_engine = || { + let mut engine = Engine::new("dev_old".into(), config.clone(), Default::default(), 0); + engine.set_output(true, false); + engine + }; + // Without announcements the old engine takes over after the timeout: + // this is what a missing playback snapshot used to cause. + let mut starved = start_engine(); + let mut now = 0; + let first = serde_json::from_str::(&{ + a.sync.playback_tick(true, true).unwrap(); + publish(&a, state.clone()); + hello_json(&a, "dev_old") + }) + .unwrap(); + let legacy::WireMessage::Hello { + playback: Some(first), + .. + } = first + else { + panic!("the old device gets a playback snapshot"); + }; + starved.observe(&a.id, first.coordination.as_ref().unwrap(), now); + while now <= config.owner_timeout_ms + 2 * config.discovery_ms { + now += 1_000; + starved.heartbeat(now); + starved.tick(now); + } + assert_eq!(starved.owner(), Some("dev_old")); + + // With the redacted snapshots of every sync round it never does. + let mut old = start_engine(); + let mut now = 0; + while now <= 3 * config.owner_timeout_ms { + a.sync.playback_tick(true, true).unwrap(); + publish(&a, state.clone()); + let json = hello_json(&a, "dev_old"); + assert!(!json.contains(&episode.audio_url), "{json}"); + assert!(!json.contains(&episode.episode_title), "{json}"); + let legacy::WireMessage::Hello { + playback: Some(snapshot), + .. + } = serde_json::from_str(&json).unwrap() + else { + panic!("the old device gets a playback snapshot"); + }; + assert_eq!(snapshot.state.queue.len(), 2, "no item is stripped"); + assert_eq!(snapshot.state.queue[0].title, "Song"); + assert_eq!( + snapshot.state.queue[1].title, + music_dht::device_sync::PRIVATE_ITEM_TITLE + ); + old.observe(&a.id, snapshot.coordination.as_ref().unwrap(), now); + old.heartbeat(now); + old.tick(now); + assert_eq!(old.owner(), Some(a.id.as_str()), "at {now} ms"); + now += 2_000; + } + // The queue this device keeps is unchanged. + let local = lock(&a.sync.playback).local.clone().unwrap(); + assert!(local.state.queue[1].podcast_episode_ref().is_some()); +} + /// Feed and audio URLs may carry private tokens; the debug log (shown in /// the Logs tab) never prints them. #[test]