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 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-19 19:22:19 +02:00
1 parent 6f3ed4b7ee
commit 3af0e8ccc9
6 files changed
+219 -48

No files matched your search

+139 -32
View File
@@ -319,10 +319,11 @@ pub(crate) fn jam_tracks_allowed(tracks: &[Value]) -> 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<i64>,
/// `current_track_id` written together with this value.
#[serde(default)]
pub(crate) legacy_current_track_id: Option<i64>,
/// `queue_position` written together with this value (`None`: unknown,
/// the value is not used).
#[serde(default)]
pub(crate) legacy_queue_position: Option<i32>,
}
/// 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<i64>,
/// `current_track_id`.
pub(crate) current_track_id: Option<i64>,
/// `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<StoredQueueItem>,
position: usize,
legacy_queue: Vec<i64>,
legacy: LegacyColumns,
) -> Option<Self> {
(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<Self> {
/// 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<Self> {
let stored = serde_json::from_value::<Self>(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<i64>) {
/// 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<i64>, 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()
);