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

+17
View File
@@ -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/`.
+21 -8
View File
@@ -1438,12 +1438,14 @@ async fn delete_entities(
}
}
// Playback queues contain local IDs rather than foreign keys.
let states: Vec<(i64, Option<i64>, String, Option<serde_json::Value>)> = 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<i64>, String, Option<serde_json::Value>, i32);
let states: Vec<QueueRow> = 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<i64> = 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 {
+15 -4
View File
@@ -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 {
+7
View File
@@ -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?;
+20 -4
View File
@@ -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<i64> = 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<queue_items::Stor
queue_items::StoredQueue::new(
items,
dto.queue_items_position.unwrap_or(0),
dto.queue.clone(),
queue_items::LegacyColumns {
queue: dto.queue.clone(),
current_track_id: dto.current_track_id,
queue_position: dto.queue_position,
},
)
}
+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()
);