Keep older devices hearing from a podcast queue owner

A device below sync v4 got no playback snapshot while the queue held an
episode, so its engine never heard the owner's heartbeat and took
playback over by automatic failover after two minutes; this device then
adopted its queue and the episodes were gone. Send such peers the
coordination envelope with the queue redacted like for Jam: every
episode becomes an opaque "Private item", nothing is stripped, and their
commands stay refused while the queue has episodes.

This departs from FRID PLAYBACK_PROTOCOL.md rule 1 ("send None") and is
reported as a contract gap.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-19 21:40:07 +02:00
1 parent 70df945ada
commit 8d87fe3959
6 files changed
+153 -17

No files matched your search

+3 -1
View File
@@ -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;
+8 -1
View File
@@ -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
+3 -1
View File
@@ -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.
+6 -1
View File
@@ -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.
+25 -9
View File
@@ -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<PlaybackSnapshot> {
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<()> {
+108 -4
View File
@@ -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::<legacy::WireMessage>(&{
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]