From 3af0e8ccc95225b438014c8f6477e66fb501258f Mon Sep 17 00:00:00 2001 From: Sanapach Date: Thu, 19 Nov 2026 19:22:19 +0200 Subject: [PATCH] Keep a rollback to 0.12 safe for sync and the typed queue Release 0.12 fails a whole sync batch on a podcast operation kind, so rolling back is only safe after the relayed podcast operations are removed: document the step in docs/administration.md and run it in the m_0055 backwards operation. The typed queue now records the current track id and queue position written with it, next to the legacy ids. A 0.12 release that only moved to another track in the same queue no longer leaves a stale typed position that the next upgrade would restore. Jam placeholders are never stored in a user's own typed queue. Co-Authored-By: Claude Opus 5.5 --- docs/administration.md | 17 ++++ src/admin/metadata_fix.rs | 29 +++++-- src/library_cleanup.rs | 19 ++++- src/music/mod.rs | 7 ++ src/player/mod.rs | 24 +++++- src/player/queue_items.rs | 171 +++++++++++++++++++++++++++++++------- 6 files changed, 219 insertions(+), 48 deletions(-) diff --git a/docs/administration.md b/docs/administration.md index 9bbdbe5..1c7e615 100644 --- a/docs/administration.md +++ b/docs/administration.md @@ -79,6 +79,23 @@ them. A device that does not support podcasts yet (device-sync protocol below it as the playback device shows that it needs an update, and the episodes stay in the queue. Jam guests see podcast episodes of the host only as private items. +### Rolling back to 0.12 + +Release 0.13 relays podcast synchronization operations from other Furumi +players. Release 0.12 cannot read them: device synchronization would fail for +every device that has not received them yet. Before you start a 0.12 release +on a database that 0.13 used, stop the server and remove those operations: + +```sql +DELETE FROM furumusic__fed_sync_ops WHERE kind LIKE 'podcast\_%'; +``` + +Devices that support podcasts keep their own podcast state. The relay table +`furumusic__fed_podcast_relay` and the typed queue column can stay: 0.12 +ignores them, and after the next upgrade 0.13 returns the relayed podcast state +in its snapshots again and uses the typed queue only while it matches the +queue, current track and position that 0.12 saved. + ## Admin statistics The only admin interface is `/admin/v2`, also reachable from `/admin/`. diff --git a/src/admin/metadata_fix.rs b/src/admin/metadata_fix.rs index 8416b4d..33b4954 100644 --- a/src/admin/metadata_fix.rs +++ b/src/admin/metadata_fix.rs @@ -1438,12 +1438,14 @@ async fn delete_entities( } } // Playback queues contain local IDs rather than foreign keys. - let states: Vec<(i64, Option, String, Option)> = sqlx::query_as( - "SELECT id,current_track_id,queue_json,queue_items_json FROM furumusic__playback_state FOR UPDATE", + // (id, current_track_id, queue_json, queue_items_json, queue_position) + type QueueRow = (i64, Option, String, Option, i32); + let states: Vec = sqlx::query_as( + "SELECT id,current_track_id,queue_json,queue_items_json,queue_position FROM furumusic__playback_state FOR UPDATE", ) .fetch_all(&mut *conn) .await?; - for (id, current, queue_json, queue_items_json) in states { + for (id, current, queue_json, queue_items_json, queue_position) in states { let mut queue: Vec = serde_json::from_str(&queue_json).unwrap_or_default(); if !current.is_some_and(|id| deleted.tracks.contains(&id)) && !queue.iter().any(|id| deleted.tracks.contains(id)) @@ -1452,7 +1454,11 @@ async fn delete_entities( } let mut typed = crate::player::queue_items::StoredQueue::from_columns( queue_items_json.as_ref(), - &queue, + &crate::player::queue_items::LegacyColumns { + queue: queue.clone(), + current_track_id: current, + queue_position, + }, ); let before: String = sqlx::query_scalar( "SELECT to_jsonb(t)::text FROM furumusic__playback_state t WHERE id=$1", @@ -1461,14 +1467,21 @@ async fn delete_entities( .fetch_one(&mut *conn) .await?; queue.retain(|id| !deleted.tracks.contains(id)); - if let Some(typed) = &mut typed { - typed.retain_library(|id| !deleted.tracks.contains(&id), queue.clone()); - } - let queue_items_json = typed.map(serde_json::to_value).transpose()?; let current = current.filter(|id| !deleted.tracks.contains(id)); let position = current .and_then(|id| queue.iter().position(|x| *x == id)) .unwrap_or(0) as i32; + if let Some(typed) = &mut typed { + typed.retain_library( + |id| !deleted.tracks.contains(&id), + crate::player::queue_items::LegacyColumns { + queue: queue.clone(), + current_track_id: current, + queue_position: position, + }, + ); + } + let queue_items_json = typed.map(serde_json::to_value).transpose()?; let after: String = sqlx::query_scalar("UPDATE furumusic__playback_state SET current_track_id=$2,queue_json=$3,queue_position=$4,queue_items_json=$5,position_ms=CASE WHEN current_track_id IS DISTINCT FROM $2 THEN 0 ELSE position_ms END WHERE id=$1 RETURNING to_jsonb(furumusic__playback_state)::text") .bind(id).bind(current).bind(serde_json::to_string(&queue)?).bind(position).bind(queue_items_json).fetch_one(&mut *conn).await?; archived.push(ArchivedRows { diff --git a/src/library_cleanup.rs b/src/library_cleanup.rs index 4c4df6d..ea38851 100644 --- a/src/library_cleanup.rs +++ b/src/library_cleanup.rs @@ -749,12 +749,13 @@ async fn cleanup_playback_states( let original_queue = queue.clone(); let mut typed = crate::player::queue_items::StoredQueue::from_columns( state.queue_items_json.as_ref(), - &original_queue, + &crate::player::queue_items::LegacyColumns { + queue: original_queue.clone(), + current_track_id: state.current_track_id, + queue_position: state.queue_position, + }, ); queue.retain(|track_id| !deleted.contains(track_id)); - if let Some(typed) = &mut typed { - typed.retain_library(|track_id| !deleted.contains(&track_id), queue.clone()); - } let current_track_id = state.current_track_id.filter(|id| !deleted.contains(id)); if queue == original_queue && current_track_id == state.current_track_id { continue; @@ -771,6 +772,16 @@ async fn cleanup_playback_states( .clamp(0, i32::try_from(queue.len() - 1).unwrap_or(i32::MAX)) } }); + if let Some(typed) = &mut typed { + typed.retain_library( + |track_id| !deleted.contains(&track_id), + crate::player::queue_items::LegacyColumns { + queue: queue.clone(), + current_track_id, + queue_position, + }, + ); + } let position_ms = if current_track_id.is_some() { state.position_ms } else { diff --git a/src/music/mod.rs b/src/music/mod.rs index c625934..fcd4de3 100644 --- a/src/music/mod.rs +++ b/src/music/mod.rs @@ -2908,8 +2908,15 @@ pub mod db_migrations { Ok(()) } + // Release 0.12.x parses every unacknowledged operation it sends to a + // peer and fails the whole batch on an unknown kind, so the podcast + // operations relayed by 0.13 must go before it runs again (see + // docs/administration.md, "Rolling back to 0.12"). #[cot::db::migrations::migration_op] async fn drop_fed_podcast_relay(ctx: migrations::MigrationContext<'_>) -> cot::db::Result<()> { + ctx.db + .raw("DELETE FROM furumusic__fed_sync_ops WHERE kind LIKE 'podcast\\_%'") + .await?; ctx.db .raw("DROP TABLE IF EXISTS furumusic__fed_podcast_relay") .await?; diff --git a/src/player/mod.rs b/src/player/mod.rs index 51fbfd5..e4dbe71 100644 --- a/src/player/mod.rs +++ b/src/player/mod.rs @@ -1704,7 +1704,12 @@ mod queue_persistence_tests { let stored = stored_queue_from_request(&dto).unwrap(); // Written to queue_items_json and read back with the legacy ids. let column = serde_json::to_value(&stored).unwrap(); - let loaded = queue_items::StoredQueue::from_columns(Some(&column), &[3, 4]).unwrap(); + let row = queue_items::LegacyColumns { + queue: dto.queue.clone(), + current_track_id: dto.current_track_id, + queue_position: dto.queue_position, + }; + let loaded = queue_items::StoredQueue::from_columns(Some(&column), &row).unwrap(); assert_eq!(loaded, stored); assert_eq!(loaded.position, 1); let items = browser_queue_items(&offline_pool(), &loaded).await.unwrap(); @@ -6745,8 +6750,15 @@ async fn get_state_handler( let dto = match state { Some(s) => { let queue: Vec = serde_json::from_str(&s.queue_json).unwrap_or_default(); - // Prefer the typed queue while it matches `queue_json`. - let typed = queue_items::StoredQueue::from_columns(s.queue_items_json.as_ref(), &queue); + // Prefer the typed queue while it matches the legacy columns. + let typed = queue_items::StoredQueue::from_columns( + s.queue_items_json.as_ref(), + &queue_items::LegacyColumns { + queue: queue.clone(), + current_track_id: s.current_track_id, + queue_position: s.queue_position, + }, + ); let (queue_items, queue_items_position) = match typed { Some(stored) => ( Some( @@ -6815,7 +6827,11 @@ fn stored_queue_from_request(dto: &PlaybackStateDto) -> Option bool { /// Typed playback queue persisted next to the legacy `queue_json`. /// /// `queue_json` (a list of library track ids) is still written for rollback -/// to older releases. `legacy_queue` records the ids written alongside this -/// value: when `queue_json` no longer matches it (an older release or a -/// legacy-only writer changed the queue since), readers ignore the typed -/// value and fall back to `queue_json`. +/// to older releases. `legacy_queue`, `legacy_current_track_id` and +/// `legacy_queue_position` record the legacy columns written alongside this +/// value: when they no longer match the row (an older release or a +/// legacy-only writer changed the queue or moved to another track since), +/// readers ignore the typed value and fall back to the legacy columns. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub(crate) struct StoredQueue { /// Shape version, [`STORED_QUEUE_VERSION`]. @@ -336,6 +337,24 @@ pub(crate) struct StoredQueue { /// `queue_json` ids written together with this value. #[serde(default)] pub(crate) legacy_queue: Vec, + /// `current_track_id` written together with this value. + #[serde(default)] + pub(crate) legacy_current_track_id: Option, + /// `queue_position` written together with this value (`None`: unknown, + /// the value is not used). + #[serde(default)] + pub(crate) legacy_queue_position: Option, +} + +/// Legacy queue columns of a `furumusic__playback_state` row. +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub(crate) struct LegacyColumns { + /// `queue_json`: library track ids. + pub(crate) queue: Vec, + /// `current_track_id`. + pub(crate) current_track_id: Option, + /// `queue_position`. + pub(crate) queue_position: i32, } /// One persisted queue item. @@ -356,41 +375,63 @@ pub(crate) enum StoredQueueItem { impl StoredQueue { /// Builds the persisted value; `None` when the queue exceeds the bound. + /// + /// Jam private placeholders are dropped: they stand for the Jam host's + /// items, never for items of this user's own queue. pub(crate) fn new( items: Vec, position: usize, - legacy_queue: Vec, + legacy: LegacyColumns, ) -> Option { - (items.len() <= MAX_STORED_QUEUE_ITEMS).then(|| Self { + if items.len() > MAX_STORED_QUEUE_ITEMS { + return None; + } + let mut stored = Self { version: STORED_QUEUE_VERSION, - position: position.min(items.len().saturating_sub(1)), + position, items, - legacy_queue, - }) + legacy_queue: Vec::new(), + legacy_current_track_id: None, + legacy_queue_position: None, + }; + stored.retain_items(|item| match item { + StoredQueueItem::Library { .. } => true, + StoredQueueItem::External { track } => !track.is_private_placeholder(), + }); + stored.set_legacy(legacy); + Some(stored) } - /// Reads the typed column, preferring it over `queue_json` only when it - /// has a known version and still matches the legacy ids. - pub(crate) fn from_columns(typed: Option<&Value>, legacy_queue: &[i64]) -> Option { + /// Reads the typed column, preferring it over the legacy columns only + /// when it has a known version and was written together with exactly + /// these legacy values. + pub(crate) fn from_columns(typed: Option<&Value>, legacy: &LegacyColumns) -> Option { let stored = serde_json::from_value::(typed?.clone()).ok()?; (stored.version == STORED_QUEUE_VERSION - && stored.legacy_queue == legacy_queue + && stored.legacy_queue == legacy.queue + && stored.legacy_current_track_id == legacy.current_track_id + && stored.legacy_queue_position == Some(legacy.queue_position) && stored.items.len() <= MAX_STORED_QUEUE_ITEMS) .then_some(stored) } /// Removes library tracks rejected by `keep` and records the new legacy - /// ids. The current position follows its item, or the item after it when - /// the current item was removed. - pub(crate) fn retain_library(&mut self, keep: impl Fn(i64) -> bool, legacy_queue: Vec) { + /// columns. The current position follows its item, or the item after it + /// when the current item was removed. + pub(crate) fn retain_library(&mut self, keep: impl Fn(i64) -> bool, legacy: LegacyColumns) { + self.retain_items(|item| match item { + StoredQueueItem::Library { track_id } => keep(*track_id), + StoredQueueItem::External { .. } => true, + }); + self.set_legacy(legacy); + } + + fn retain_items(&mut self, keep: impl Fn(&StoredQueueItem) -> bool) { + let original_position = self.position; let mut position = self.position; let mut index = 0; - let original_position = self.position; self.items.retain(|item| { - let retained = match item { - StoredQueueItem::Library { track_id } => keep(*track_id), - StoredQueueItem::External { .. } => true, - }; + let retained = keep(item); if !retained && index < original_position { position = position.saturating_sub(1); } @@ -398,7 +439,12 @@ impl StoredQueue { retained }); self.position = position.min(self.items.len().saturating_sub(1)); - self.legacy_queue = legacy_queue; + } + + fn set_legacy(&mut self, legacy: LegacyColumns) { + self.legacy_queue = legacy.queue; + self.legacy_current_track_id = legacy.current_track_id; + self.legacy_queue_position = Some(legacy.queue_position); } } @@ -535,6 +581,14 @@ mod tests { assert!(jam_tracks_allowed(&[library(9)])); } + fn legacy(queue: &[i64], current_track_id: Option, queue_position: i32) -> LegacyColumns { + LegacyColumns { + queue: queue.to_vec(), + current_track_id, + queue_position, + } + } + #[test] fn stored_queue_prefers_typed_value_only_while_legacy_ids_match() { let items = vec![ @@ -544,7 +598,9 @@ mod tests { }, StoredQueueItem::Library { track_id: 4 }, ]; - let stored = StoredQueue::new(items, 1, vec![3, 4]).unwrap(); + // The episode is current: the browser wrote its placeholder id. + let written = legacy(&[3, -11, 4], Some(-11), 1); + let stored = StoredQueue::new(items, 1, written.clone()).unwrap(); let value = serde_json::to_value(&stored).unwrap(); assert_eq!(value["version"], 1); assert_eq!(value["items"][1]["kind"], "external"); @@ -553,15 +609,59 @@ mod tests { "podcast_episode" ); assert_eq!( - StoredQueue::from_columns(Some(&value), &[3, 4]), + StoredQueue::from_columns(Some(&value), &written), Some(stored.clone()) ); // A rollback release rewrote queue_json: fall back to it. - assert_eq!(StoredQueue::from_columns(Some(&value), &[3]), None); + assert_eq!( + StoredQueue::from_columns(Some(&value), &legacy(&[3, 4], Some(4), 1)), + None + ); + // A rollback release kept the ids but moved to another track (Next + // or a click): the typed position is stale, fall back as well. + assert_eq!( + StoredQueue::from_columns(Some(&value), &legacy(&[3, -11, 4], Some(4), 2)), + None + ); + assert_eq!( + StoredQueue::from_columns(Some(&value), &legacy(&[3, -11, 4], Some(-11), 0)), + None + ); + // Values without the recorded current item are not trusted. + let mut unknown = value.clone(); + unknown + .as_object_mut() + .unwrap() + .remove("legacy_queue_position"); + assert_eq!(StoredQueue::from_columns(Some(&unknown), &written), None); let mut future = value.clone(); future["version"] = serde_json::json!(2); - assert_eq!(StoredQueue::from_columns(Some(&future), &[3, 4]), None); - assert_eq!(StoredQueue::from_columns(None, &[3, 4]), None); + assert_eq!(StoredQueue::from_columns(Some(&future), &written), None); + assert_eq!(StoredQueue::from_columns(None, &written), None); + } + + #[test] + fn stored_queue_never_keeps_jam_placeholders() { + let items = vec![ + StoredQueueItem::Library { track_id: 3 }, + StoredQueueItem::External { + track: Box::new(PlaybackTrack::private_placeholder()), + }, + StoredQueueItem::External { + track: Box::new(PlaybackTrack::podcast_episode(episode())), + }, + StoredQueueItem::Library { track_id: 4 }, + ]; + let stored = StoredQueue::new(items.clone(), 3, legacy(&[3, 4], Some(4), 1)).unwrap(); + assert_eq!( + stored.items, + vec![items[0].clone(), items[2].clone(), items[3].clone()] + ); + assert_eq!(stored.position, 2); + // A current placeholder hands the position to the next item. + let stored = StoredQueue::new(items.clone(), 1, legacy(&[3, 4], None, 0)).unwrap(); + assert_eq!(stored.position, 1); + assert_eq!(stored.items[1], items[2]); } #[test] @@ -573,20 +673,27 @@ mod tests { }, StoredQueueItem::Library { track_id: 4 }, ]; - let mut stored = StoredQueue::new(items.clone(), 1, vec![3, 4]).unwrap(); - stored.retain_library(|id| id != 3, vec![4]); + let mut stored = StoredQueue::new(items.clone(), 1, legacy(&[3, 4], None, 0)).unwrap(); + stored.retain_library(|id| id != 3, legacy(&[4], None, 0)); assert_eq!(stored.items, items[1..].to_vec()); assert_eq!(stored.position, 0); assert_eq!(stored.legacy_queue, vec![4]); + // The cleanup's new legacy columns are what readers compare with. + let value = serde_json::to_value(&stored).unwrap(); + assert_eq!( + StoredQueue::from_columns(Some(&value), &legacy(&[4], None, 0)), + Some(stored) + ); - let mut current_removed = StoredQueue::new(items.clone(), 2, vec![3, 4]).unwrap(); - current_removed.retain_library(|id| id != 4, vec![3]); + let mut current_removed = + StoredQueue::new(items.clone(), 2, legacy(&[3, 4], Some(4), 1)).unwrap(); + current_removed.retain_library(|id| id != 4, legacy(&[3], None, 0)); assert_eq!(current_removed.position, 1); assert!( StoredQueue::new( vec![items[0].clone(); MAX_STORED_QUEUE_ITEMS + 1], 0, - vec![] + LegacyColumns::default() ) .is_none() );