MR-W1 из плана подкастов (PODCASTS_PLAN.md, решения Р4, Р5, Р6 для веба). Подкасты в UI, RSS и хранилище подкастов будут в MR-W2. Здесь веб перестаёт терять элементы очереди и состояние подкастов, которые проходят через него, и начинает объявлять протокол синхронизации устройств v4.
1. Общие DTO вместо приватных копий
Приватные копии wire-типов удалены из src/federation/devices.rs: InviteWire, DeviceProfileWire, SyncedFedTrack, PlaybackTrack, PlaybackStateWire, SyncOpWire, SyncOpPayload, SyncSnapshot*, WireMessage. Вместо них используется music_dht::device_sync. Вспомогательные функции приглашений и чтения/записи строк тоже берутся из music_dht.
Совместимость проверяется так:
wire_compat_tests.rs хранит дословную копию типов 0.12.4;
для v3-контента проверяется побайтовое совпадение сериализации и разбор в обе стороны;
фикстура fixtures/v3_hello.golden.json (все v3-операции, все секции snapshot, playback с координацией) — эталон формы master;
отдельно проверено, что старые типы читают p в инвайте и protocol_version в device_profile_set;
отдельно проверено, почему без отсечки нельзя: старые типы падают на неизвестном kind подкастовой операции и теряют source у выпуска.
2. Очередь без потерь: явный source в мосте браузер ↔ wire
Новый модуль src/player/queue_items.rs. Каждый элемент, который не является треком библиотеки, превращается во внешний элемент браузера: поля для показа, source (PlaybackSource) и wire_track (исходный PlaybackTrack без изменений). Это выпуски подкастов, Private-плейсхолдеры Jam и неразрешённая музыка федерации.
Обратно в wire уходит сохранённый wire_track. Поэтому выпуск проходит путь пир → сервер → браузер → сервер → пир без изменений.
Фильтр, который молча выкидывал элементы без числового id, удалён. queue_pos больше не сдвигается.
Поведение музыки библиотеки не изменилось.
Плеер:
выпуски показываются с меткой «Подкаст · пока не воспроизводится в веб-плеере», плейсхолдеры — «Приватный элемент · скрыт владельцем»;
next/prev их пропускают;
клик по такому элементу при локальном воспроизведении ничего не делает;
аудио для них не загружается;
если звук играет на другом устройстве (TUI v4), выбор передаётся туда;
если такой элемент текущий, его позиция хранится как позиция элемента: при передаче TUI → веб → TUI выпуск возвращается с той же позицией, а не со временем старого <audio> или нулём;
если веб сам сделал выпуск текущим (Next, автопереход, клик, команда play), позицию он не знает и не выдумывает 0: в состоянии устройства передаётся position_unknown: true, а сервер перед передачей на другое устройство берёт позицию возобновления из релейного регистра прогресса (resume_position_ms(), без регистра — 0) и поднимает progress_generation элемента до поколения регистра. Так же сервер поступает с командами play_track/play_from_index/next/prev, которые веб отправляет на TUI как пульт;
Play/resume на таком элементе переходит к следующему воспроизводимому (с переходом в начало при repeat «all»); repeat «one» не повторяет элемент, который веб не может играть;
Next (и автопереход) при repeat «all» или shuffle проходит мимо таких элементов в конце очереди и продолжает с первого воспроизводимого, а не останавливается;
Prev на таком элементе сразу переходит к предыдущему (перезапускать нечего), seek меняет сохранённую позицию элемента.
queue_json по-прежнему записывается, чтобы можно было откатиться на старую версию.
При чтении типизированная колонка используется, только пока записанные с ней старые колонки (queue_json, current_track_id, queue_position) совпадают со строкой. Иначе (откат на старую версию, запись только старым кодом, в том числе переход старого релиза на другой трек той же очереди) берутся старые колонки.
Jam-плейсхолдеры (private) в собственную очередь пользователя не сохраняются никогда.
Типизированную колонку тоже обновляют:
очистка библиотеки (library_cleanup);
удаление и undo в Metadata Repair. Undo удалений, записанных до m_0054 (в архиве нет ключа queue_items_json), сравнивает строку без этой колонки и по-прежнему работает.
API /api/player/state получил необязательные поля queue_items и queue_items_position. Старые клиенты работают как раньше.
4. Протокол v4 и отсечка
Почему веб объявляет v4.
Журнал операций уже хранил payload в общем виде. Поэтому с общими типами подкастовые операции сохраняются и пересылаются.
Подкастовые секции snapshot раньше отбрасывались бы. Для них добавлено минимальное хранилище без потерь — furumusic__fed_podcast_relay (миграция m_0055):
регистры из операций и snapshot сливаются функциями merge_* из music_dht::podcast;
они возвращаются в snapshot веба;
размер ограничивается для каждого сообщения через podcast_snapshot_budget;
некорректные подкастовые операции пропускаются, но подтверждаются.
Константа PROTOCOL_VERSION = 4 привязана к DEVICE_SYNC_PROTOCOL_VERSION проверкой при компиляции.
Что отправляется пиру.
Операции: ops_for_peer прячет неподдерживаемые kind ещё в SQL, чтобы курсор не застревал. Финальная проверка — op_allowed_for_peer.
Snapshot: SyncSnapshot::for_peer.
Playback snapshot отправляется, только если выполнено playback_allowed_for_peer.
PairRequest ограничивается по InviteWire::inviter_protocol_version(). Инвайты веба передают p = 4.
Версии пиров.
Собственный отчёт устройства (profile, его собственная запись в devices, DeviceProfileSet) обрабатывается через profile_protocol_version. Версии в профилях, переданных другими устройствами, — через relayed_protocol_version: они только повышают сохранённую.
Исправлены два места, где версию пира перезаписывала константа веба: DeviceProfileSet в apply_op и answer_pairing.
При первом запуске новой версии один раз отправляется DeviceProfileSet с protocol_version.
Перенос и команды.
Перенос очереди с подкастами на устройство ниже v4 запрещается до смены владельца. Ответ — HTTP 409 с сообщением «… needs an update to play podcast episodes …», оно видно в меню устройств. Выпуски из очереди не удаляются.
SetState и ActiveChanged от пира ниже v4 игнорируются, пока в очереди есть выпуски.
Jam. Гости видят состояние хоста через redact_for_jam: выпуски показываются как приватные элементы. Команды гостя с выпусками отклоняются (jam_command_allowed). Если гость присылает полную очередь, плейсхолдеры возвращаются на место хостовых элементов через restore_jam_private_items. Попытки удалить, продублировать или подложить приватный элемент отклоняются:
полная очередь, где плейсхолдеров не хватает, они повторяются или подложены;
queue_remove по индексу приватного элемента хоста (и индекс не целым числом, пока в очереди хоста есть приватные элементы: браузер хоста выполняет Number(index));
queue_clear, пока в очереди хоста есть приватные элементы.
Перемещать приватный элемент (queue_move) гостю можно. Если текущий элемент хоста приватный, гость не видит его длительность (duration_seconds = 0); позиция остаётся, как в redact_for_jam.
Проверка сервера идёт по последнему отчёту хоста, а браузер хоста выполняет накопленные команды пачкой. Поэтому сервер помечает команды участников (jam_participant: true), и браузер хоста проверяет их по своей текущей очереди (_jamParticipantCommandAllowed): удаление приватного элемента, очистка очереди с ними, добавление плейсхолдеров и полная очередь, где приватных элементов не столько же, сколько у хоста сейчас, не выполняются. Когда гость перестаёт управлять Jam (вышел или Jam исчез), плейсхолдеры удаляются из его очереди и не становятся его собственной очередью.
5. Документация и версия
docs/development.md: новый раздел о синхронизации устройств, мосте и тестах.
docs/administration.md: что видит пользователь.
CHANGELOG v0.13.0. Версия furumusic поднята до 0.13.0 (минорная).
Решения и отступления от плана
Номера миграций.m_0053 уже занят в этом же app (src/user.rs, m_0053_local_approval_and_public_shares), поэтому использованы m_0054 и m_0055. Цепочка в music/mod.rs идёт от m_0052.
Таблица furumusic__fed_podcast_relay. Это не модель подкастов, а непрозрачный кэш регистров контракта F1 (это разрешено пунктом «minimal lossless storage»). Без неё веб терял бы секции snapshot и не мог бы честно объявлять v4. В MR-W2 данные можно импортировать в нормальные таблицы.
Минимальная версия 2 при отсечке listen_recorded. Веб работает только по furumi/sync/2, значит любой пир поддерживает хотя бы v2. Без этого события прослушивания в PairRequest к инвайтеру TUI 0.3 (инвайт без p, то есть версия 1) терялись бы навсегда: векторы только растут, а в snapshot прослушиваний нет. На отсечку подкастов (v4) это не влияет.
Jam в вебе. Это внутренний механизм хаба между пользователями одного сервера, а не протокол music_dht::jam. Поэтому решения принимают функции F1 над wire-«тенью» очереди, а JSON-элементы переставляются по тому же правилу.
Мелкие исправления по ходу:
проверка переноса до смены владельца в хабе — раньше хаб переключался, даже если перенос потом падал;
queue_pos больше не съезжает при пропуске битого элемента;
поиск content_id в БД делается, только если его нет в JSON, — результат тот же;
assert в interop_tests теперь принимает версию 3..=4.
playback_rate. Поле зарезервировано и через мост веба не переносится. Веб отправляет None, что получатели читают как 1.0.
Исправления по первому ревью
Все пять замечаний ревью подтвердились и исправлены отдельными коммитами с регрессионными тестами.
(high) Передача выпуска TUI → веб → TUI теряла позицию. Ветка недоступного элемента в _executeRemoteCommand вызывала _applyRemotePlaybackState + _pauseLocal, а _tickRemoteProgress на активном устройстве время не ставит, поэтому _devicePlaybackStatePayload отдавал время старого <audio> (или 0). Теперь _showUnplayableQueueItem(track, position) выгружает прежний источник и хранит переданную позицию (также при восстановлении состояния, _syncLocalPlaybackState и _playLocal). _devicePlaybackStatePayload берёт audio.currentTime только для элемента, который реально загружен в <audio> (_currentItemHasLocalAudio). Поздний timeupdate после выгрузки аудио позицию не сбрасывает. Тесты: node (transfer_state с выпуском на 1200 с при <audio> на 95 с и на свежей странице → отчёт 1200 с, пауза, индекс 1; музыка по-прежнему отдаёт время <audio>), Rust (podcast_queue_survives_server_browser_server_round_trip: position_secs 1200 проходит пир → браузер → пир).
(medium) Бесконечная рекурсия при repeat «one» на неиграбельном текущем элементе.resume() больше не вызывает next(), а переходит через _skipUnplayableCurrentItem; next() не применяет repeat «one» к элементу, который веб не может играть. Тест node: repeat one/off/all с единственным выпуском — без исключения, элемент и позиция остаются; с музыкой после выпуска — играет следующий трек; repeat all — переход к первому.
(medium) Гости Jam могли удалить приватные элементы хоста.restore_jam_command_payload теперь отклоняет queue_remove приватного элемента и queue_clear очереди с приватными элементами (см. раздел Jam). Тест jam_command_tests::participants_cannot_remove_or_clear_private_items.
(low) Длительность приватного текущего элемента была видна гостю.redact_playback_state_for_jam обнуляет duration_seconds (текущий элемент берётся из track, а без него — из tracks[index]). Тест jam_command_tests::redacted_current_episode_has_no_duration.
(low) Undo Metadata Repair для записей до m_0054.restore_deleted сравнивает to_jsonb(t) - 'queue_items_json', если в архиве нет этого ключа; колонка при восстановлении становится NULL, и чтение берёт queue_json. Изменённая после удаления строка по-прежнему отклоняется. Тест undo_accepts_playback_archives_written_before_the_typed_queue (ignored, нужна мигрированная БД).
Исправления по повторному ревью
Все семь замечаний подтвердились (проверено по коду и сценариями ревьюера) и исправлены новыми коммитами с регрессионными тестами.
(medium) Веб выдумывал позицию 0 для выпуска, ставшего текущим без переданной позиции (Next/автопереход на выпуск, play_from_index от другого браузера или гостя, Next/клик по выпуску при управлении TUI). 0 уходил на TUI как позиция передачи или как seek и записывался в прогресс явным действием. Исправлено: position_unknown в браузере и в состоянии хаба (PlayerDevicePlaybackStateDto.position_unknown), заполнение позиции и поколения из furumusic__fed_podcast_relay в playback_state_from_browser_json (передача, takeover, snapshot, команды пульта), команды play_*/next/prev на другой элемент помечают позицию неизвестной, seek и перезапуск — нет. Тесты: commands_that_select_an_item_do_not_know_its_position, unknown_episode_position_resumes_from_the_progress_register, known_positions_and_music_never_read_the_progress_register, Postgres postgres_unknown_episode_position_and_rollback_cleanup (передача на TUI и удалённый Next получают 1200 с и поколение 9), node «an episode reached without its position reports it as unknown, never as 0».
(medium) Проверка удаления/очистки приватных элементов гостем шла по устаревшему снимку хоста. Исправлено пометкой jam_participant и проверкой в браузере хоста (см. Jam). Тесты: participant_commands_reach_the_host_stamped, node «the Jam host keeps its private items against stale participant commands» (move → remove в одной пачке оставляет выпуск; clear, добавление плейсхолдера и устаревшая полная очередь отклоняются).
(low) При repeat «all»/shuffle воспроизведение останавливалось на выпуске в конце очереди. Исправлено в playQueueIndex. Тест node «repeat all and shuffle continue past a trailing unplayable item».
(low) Prev не уходил с переданного выпуска при позиции > 3 с, seek игнорировался. Исправлено в prev()/seek()/seekRelative(). Тест node «prev and seek work on a handed-off episode».
(low) После выхода из Jam очередь хоста с плейсхолдерами становилась очередью гостя. Исправлено _dropJamPlaceholders при выходе из управления Jam, а сервер не сохраняет плейсхолдеры в типизированную очередь (StoredQueue::new). Тесты: node «leaving a Jam drops the host placeholders from the guest queue», «the devices store drops placeholders…», Rust stored_queue_never_keeps_jam_placeholders.
(medium) Утверждение «откат на 0.12.x возможен» было неверным: 0.12 падает на всей пачке операций, если в журнале есть подкастовая операция. Исправлено: шаг перед откатом описан в docs/administration.md («Rolling back to 0.12», DELETE FROM furumusic__fed_sync_ops WHERE kind LIKE 'podcast\_%'), тот же запрос (DELETE_PODCAST_SYNC_OPS_SQL) выполняет обратная операция m_0055. Postgres-тест разбирает журнал дословными типами 0.12.4: до очистки ошибка, после — читается, команды воспроизведения с source остаются.
(low) После отката и повторного обновления типизированная очередь могла восстановить не тот текущий элемент. Исправлено сравнением current_track_id и queue_position (см. раздел 3). Тест stored_queue_prefers_typed_value_only_while_legacy_ids_match дополнен случаями «0.12 перешёл на другой трек той же очереди».
Совместимость и версии
music-dht 0.5.0 → 0.6.0. Cargo.lock и [patch]: последний коммит этого MR, «Point frid deps at the fork branch», подключает неопубликованный frid из форка: в [patch.crates-io] в Cargo.tomlmusic-dht указывают на git = "https://gt.hexor.cy/Sanapach/frid.git", branch = "podcasts/contract", а в Cargo.lock у frid-крейтов (включая federation-net) стоит source = "git+https://gt.hexor.cy/Sanapach/frid.git?branch=…#<sha>". После публикации крейтов на crates.io эти строки удаляются, и lock перегенерируется ещё раз.
furumusic 0.12.4 → 0.13.0.
ALPN не меняется (furumi/sync/2).
С пирами v3 (TUI 0.3.x, веб 0.12.x) музыка, плейлисты, лайки, история и playback только с музыкой работают как раньше, JSON для них побайтово тот же. Подкастовые операции, секции snapshot и playback с выпусками им не отправляются.
БД: две новые миграции с обратными операциями. queue_json, current_track_id и queue_position по-прежнему пишутся.
Откат на 0.12.x возможен только после удаления подкастовых операций из журнала: сервер 0.12 не разбирает их и не синхронизирует ни одно устройство, которое их ещё не получило. Перед запуском 0.12 остановить сервер и выполнить DELETE FROM furumusic__fed_sync_ops WHERE kind LIKE 'podcast\_%'; (описано в docs/administration.md; обратная операция m_0055 делает то же, но старый бинарник обратные операции не запускает). Таблицу relay и колонку queue_items_json можно оставить: 0.12 их не читает.
Новые ключи браузерного JSON: position_unknown в состоянии устройства (только true, иначе отсутствует) и jam_participant в командах участников Jam. Старые браузеры их игнорируют. В wire-протокол они не попадают.
Как проверено (macOS 26 / Darwin 25.5, arm64; rustc 1.100.0 и 1.97.0)
После исправлений по повторному ревью (ветка на c1cd689), CARGO_TARGET_DIR=/Users/krypton/furumi/gitea/.targets/web-w1, music-dht из .cargo-патча на frid-f1:
cargo fmt --all -- --check: 20 диффов в src/admin/mod.rs (18), src/agent/dedup.rs (1), src/jobs/inbox_process.rs (1) — ровно те же есть на master, эти файлы не трогались. Мои файлы отформатированы.
cargo clippy --all-targets --message-format=short -- -D warnings: на master уже падает. Набор диагностик (файл + сообщение) ветки совпадает с master: 80 на 1.100.0 и 75 на cargo +1.97.0 (CI). Новая type_complexity в metadata_fix.rs исправлена псевдонимом типа.
cargo test --all-targets -- --skip real_transcodes_match_and_keep_distinct_bitrates: 154 passed, 0 failed, 14 ignored (было 149/13). Пропущенный тест требует ffmpeg и без него падает и на master. Каждый новый коммит отдельно проходил cargo test и node-тесты.
node --test tests/*.test.cjs: 43 pass, 0 fail (tests/player_queue_sources.test.cjs — 14 тестов production-методов плеера в vm; новые тесты на шаблоне до исправлений падают).
PostgreSQL: временный контейнер postgres:16-alpine на случайном порту 127.0.0.1, БД мигрирована двумя запусками debug-сервера (FURU_DATABASE_URL=…; первый запуск на пустой БД паникует в планировщике после миграций — известная проблема master; m_0054, m_0055 применились). Затем: FURU_DEVICE_SYNC_TEST_DATABASE_URL=… FURU_METADATA_FIX_TEST_DATABASE_URL=… cargo test --all-targets -- --ignored postgres_ undo_accepts_playback_archives_written_before_the_typed_queue:
undo_accepts_playback_archives_written_before_the_typed_queue — ok (в прошлом раунде не запускался);
ещё два теста, попавшие под фильтр postgres_ (oidc::approval_tests…, admin::statistics…), требуют других переменных окружения и к MR не относятся.
Контейнер удалён.
Ранее (до повторного ревью): миграции на чистой БД проверены через \d и information_schema; ручная E2E-проверка в headless Chrome 157 через CDP (2 строки .queue-track.unplayable, у аудио нет src, wire_track выпуска после _saveState() побайтово равен исходному, ошибок JS нет).
Ограничения
Воспроизведение подкастов в вебе будет в MR-W2. Пока выпуски сохраняются, помечаются и пропускаются.
В relay-таблице сеансы прослушивания копятся без предела, ограничивается только исходящий snapshot.
Отказ удалённой команды (SetState) устройству ниже v4 возвращает 400, но в UI сообщение видно только при переносе через меню устройств: sendCommand ошибки не показывает.
Позиция для выпуска с неизвестной позицией берётся из релейного регистра. Если операция прогресса от TUI ещё не дошла до сервера, будет взят более старый регистр (или 0, если регистра нет) — это ограничение того, что сервер знает; заметно только в окне до синхронизации.
После перезагрузки страницы сохранённая позиция 0 для текущего выпуска считается неизвестной (флаг не сохраняется в furumusic__playback_state), и сервер берёт позицию из регистра.
При shuffle, если выбран выпуск, поиск воспроизводимого элемента идёт от выбранного индекса в сторону текущего, затем по кругу; новой случайной выборки нет.
Гонка «устаревший индекс» для команд гостя по музыке (удалить не тот трек после перемещения) осталась, как на master; защищены только приватные элементы.
E2E в headless Chrome после исправлений по ревью не повторялся; поведение плеера проверено node-тестами production-методов, серверные пути — Rust- и Postgres-тестами. Реальный откат на бинарник 0.12 после очистки не запускался: вместо этого журнал разбирается дословными типами 0.12.4.
С реальным TUI проверено только межклиентским прогоном в составе всего стека (веб 0.15.0 + TUI 0.5.0, см. «Межклиентская проверка»), а не на вершине этой ветки. Тест localhost_tui_peer не запускался. Не проверены Playwright browser-*.cjs, Linux и Windows.
Уже есть на master, не связано с этим MR:
cargo fmt --check и clippy -D warnings падают;
при первом старте на пустой БД планировщик паникует до окончания миграций (повторный старт работает).
Зависимости от других MR
Зависит от MR-F1 (frid, ветка podcasts/contract, music-dht 0.6.0: music_dht::podcast, device_sync v4). До публикации подключается через [patch.crates-io].
MR-W2 будет строиться на этом MR: queue_items, podcast_relay, queue_items_json.
Ветка Sanapach/furumi-web:podcasts/queue-source → Furumi/furumi-web:master (база 9b92385, вершина 4f17fee). Последний коммит — «Point frid deps at the fork branch» (4f17fee, см. «Совместимость и версии»).
Все двенадцать коммитов относятся к этому MR (база origin/master):
75c6702 Update music-dht to 0.6.0
b558cf3 Relay device-sync v4 and keep podcast queue items
c14ab8d Document podcast queue support and release 0.13.0
4d0b352 Keep the episode position and skip unplayable items safely in the player
a9736e5 Keep Jam guests from removing or timing the host's private items
19139ea Undo metadata deletions archived before the typed queue column
ab7202f Note the podcast queue fixes in the changelog
d1be583 Resume unknown episode positions from progress, not 0
6f3ed4b Check Jam participant commands against the host queue
3af0e8c Keep a rollback to 0.12 safe for sync and the typed queue
a04a746 Note the review fixes in the changelog and docs
c1cd689 Test episode resume positions and rollback cleanup on PostgreSQL
4f17fee Point frid deps at the fork branch
Межклиентская проверка
Мост очереди, отсечка v4 и редакция Jam из этого MR проверены в составе всего стека: веб 0.15.0 (0e985b4) с TUI 0.5.0 (409188b), старые TUI 0.3.5 и веб 0.12.4, frid 9c82f6d. Прогон шёл на macOS, ленты только с 127.0.0.1, PostgreSQL в одноразовом контейнере, браузер — headless Chrome через CDP. Полная таблица — в MR-W2.
Перенос очереди с выпуском веб ↔ TUI: выпуск, очередь, позиция и пауза сохраняются (S3) — pass.
Старые пиры (S4): веб 0.12.4 в группе с новым TUI и TUI 0.3.5 в группе с новым вебом. Подкастовых данных у них нет (0 совпадений в pg_dump и файлах), плейлисты синхронизируются, перенос с выпуском отклоняется «needs an update», отправитель продолжает играть — pass.
Jam в вебе (S5): гость видит только «Private item · hidden by its owner», в его ответах API нет данных выпусков — pass.
Не прогонялось: Jam с хостом-TUI и гостем-вебом (веб не поддерживает федеративный Jam).
> **Серия «Подкасты»:** MR-F1 Furumi/frid#1 · MR-F2 Furumi/frid#2 · MR-F3 Furumi/frid#3 · MR-0 Furumi/furumi-tui#1 · MR-T1 Furumi/furumi-tui#2 · MR-T2 Furumi/furumi-tui#3 · MR-T3 Furumi/furumi-tui#4 · **MR-W1 Furumi/furumi-web#10** (этот) · MR-W2 Furumi/furumi-web#11 · MR-W3 Furumi/furumi-web#12. Порядок merge и зависимости — в разделе зависимостей ниже.
## Что сделано
MR-W1 из плана подкастов (`PODCASTS_PLAN.md`, решения Р4, Р5, Р6 для веба). Подкасты в UI, RSS и хранилище подкастов будут в MR-W2. Здесь веб перестаёт терять элементы очереди и состояние подкастов, которые проходят через него, и начинает объявлять протокол синхронизации устройств v4.
### 1. Общие DTO вместо приватных копий
- Приватные копии wire-типов удалены из `src/federation/devices.rs`: `InviteWire`, `DeviceProfileWire`, `SyncedFedTrack`, `PlaybackTrack`, `PlaybackStateWire`, `SyncOpWire`, `SyncOpPayload`, `SyncSnapshot*`, `WireMessage`. Вместо них используется `music_dht::device_sync`. Вспомогательные функции приглашений и чтения/записи строк тоже берутся из `music_dht`.
- Совместимость проверяется так:
- `wire_compat_tests.rs` хранит дословную копию типов 0.12.4;
- для v3-контента проверяется побайтовое совпадение сериализации и разбор в обе стороны;
- фикстура `fixtures/v3_hello.golden.json` (все v3-операции, все секции snapshot, playback с координацией) — эталон формы master;
- отдельно проверено, что старые типы читают `p` в инвайте и `protocol_version` в `device_profile_set`;
- отдельно проверено, почему без отсечки нельзя: старые типы падают на неизвестном `kind` подкастовой операции и теряют `source` у выпуска.
### 2. Очередь без потерь: явный `source` в мосте браузер ↔ wire
- Новый модуль `src/player/queue_items.rs`. Каждый элемент, который не является треком библиотеки, превращается во внешний элемент браузера: поля для показа, `source` (`PlaybackSource`) и `wire_track` (исходный `PlaybackTrack` без изменений). Это выпуски подкастов, Private-плейсхолдеры Jam и неразрешённая музыка федерации.
- Обратно в wire уходит сохранённый `wire_track`. Поэтому выпуск проходит путь пир → сервер → браузер → сервер → пир без изменений.
- Фильтр, который молча выкидывал элементы без числового `id`, удалён. `queue_pos` больше не сдвигается.
- Поведение музыки библиотеки не изменилось.
- Плеер:
- выпуски показываются с меткой «Подкаст · пока не воспроизводится в веб-плеере», плейсхолдеры — «Приватный элемент · скрыт владельцем»;
- next/prev их пропускают;
- клик по такому элементу при локальном воспроизведении ничего не делает;
- аудио для них не загружается;
- если звук играет на другом устройстве (TUI v4), выбор передаётся туда;
- если такой элемент текущий, его позиция хранится как позиция элемента: при передаче TUI → веб → TUI выпуск возвращается с той же позицией, а не со временем старого `<audio>` или нулём;
- если веб сам сделал выпуск текущим (Next, автопереход, клик, команда play), позицию он не знает и не выдумывает 0: в состоянии устройства передаётся `position_unknown: true`, а сервер перед передачей на другое устройство берёт позицию возобновления из релейного регистра прогресса (`resume_position_ms()`, без регистра — 0) и поднимает `progress_generation` элемента до поколения регистра. Так же сервер поступает с командами `play_track`/`play_from_index`/`next`/`prev`, которые веб отправляет на TUI как пульт;
- Play/resume на таком элементе переходит к следующему воспроизводимому (с переходом в начало при repeat «all»); repeat «one» не повторяет элемент, который веб не может играть;
- Next (и автопереход) при repeat «all» или shuffle проходит мимо таких элементов в конце очереди и продолжает с первого воспроизводимого, а не останавливается;
- Prev на таком элементе сразу переходит к предыдущему (перезапускать нечего), seek меняет сохранённую позицию элемента.
### 3. Типизированное хранение очереди
- Миграция `m_0054_add_typed_playback_queue` добавляет колонку `furumusic__playback_state.queue_items_json JSONB`.
- Колонка создаётся через `IF NOT EXISTS`, у миграции есть обратная операция.
- Формат значения: `{version: 1, position, items: [{kind: library, track_id} | {kind: external, track: PlaybackTrack}], legacy_queue, legacy_current_track_id, legacy_queue_position}`.
- `queue_json` по-прежнему записывается, чтобы можно было откатиться на старую версию.
- При чтении типизированная колонка используется, только пока записанные с ней старые колонки (`queue_json`, `current_track_id`, `queue_position`) совпадают со строкой. Иначе (откат на старую версию, запись только старым кодом, в том числе переход старого релиза на другой трек той же очереди) берутся старые колонки.
- Jam-плейсхолдеры (`private`) в собственную очередь пользователя не сохраняются никогда.
- Типизированную колонку тоже обновляют:
- очистка библиотеки (`library_cleanup`);
- удаление и undo в Metadata Repair. Undo удалений, записанных до `m_0054` (в архиве нет ключа `queue_items_json`), сравнивает строку без этой колонки и по-прежнему работает.
- API `/api/player/state` получил необязательные поля `queue_items` и `queue_items_position`. Старые клиенты работают как раньше.
### 4. Протокол v4 и отсечка
**Почему веб объявляет v4.**
- Журнал операций уже хранил payload в общем виде. Поэтому с общими типами подкастовые операции сохраняются и пересылаются.
- Подкастовые секции snapshot раньше отбрасывались бы. Для них добавлено минимальное хранилище без потерь — `furumusic__fed_podcast_relay` (миграция `m_0055`):
- регистры из операций и snapshot сливаются функциями `merge_*` из `music_dht::podcast`;
- они возвращаются в snapshot веба;
- размер ограничивается для каждого сообщения через `podcast_snapshot_budget`;
- некорректные подкастовые операции пропускаются, но подтверждаются.
- Константа `PROTOCOL_VERSION = 4` привязана к `DEVICE_SYNC_PROTOCOL_VERSION` проверкой при компиляции.
**Что отправляется пиру.**
- Операции: `ops_for_peer` прячет неподдерживаемые kind ещё в SQL, чтобы курсор не застревал. Финальная проверка — `op_allowed_for_peer`.
- Snapshot: `SyncSnapshot::for_peer`.
- Playback snapshot отправляется, только если выполнено `playback_allowed_for_peer`.
- `PairRequest` ограничивается по `InviteWire::inviter_protocol_version()`. Инвайты веба передают `p = 4`.
**Версии пиров.**
- Собственный отчёт устройства (`profile`, его собственная запись в `devices`, `DeviceProfileSet`) обрабатывается через `profile_protocol_version`. Версии в профилях, переданных другими устройствами, — через `relayed_protocol_version`: они только повышают сохранённую.
- Исправлены два места, где версию пира перезаписывала константа веба: `DeviceProfileSet` в `apply_op` и `answer_pairing`.
- При первом запуске новой версии один раз отправляется `DeviceProfileSet` с `protocol_version`.
**Перенос и команды.**
- Перенос очереди с подкастами на устройство ниже v4 запрещается до смены владельца. Ответ — HTTP 409 с сообщением «… needs an update to play podcast episodes …», оно видно в меню устройств. Выпуски из очереди не удаляются.
- `SetState` и `ActiveChanged` от пира ниже v4 игнорируются, пока в очереди есть выпуски.
**Jam.** Гости видят состояние хоста через `redact_for_jam`: выпуски показываются как приватные элементы. Команды гостя с выпусками отклоняются (`jam_command_allowed`). Если гость присылает полную очередь, плейсхолдеры возвращаются на место хостовых элементов через `restore_jam_private_items`. Попытки удалить, продублировать или подложить приватный элемент отклоняются:
- полная очередь, где плейсхолдеров не хватает, они повторяются или подложены;
- `queue_remove` по индексу приватного элемента хоста (и индекс не целым числом, пока в очереди хоста есть приватные элементы: браузер хоста выполняет `Number(index)`);
- `queue_clear`, пока в очереди хоста есть приватные элементы.
Перемещать приватный элемент (`queue_move`) гостю можно. Если текущий элемент хоста приватный, гость не видит его длительность (`duration_seconds = 0`); позиция остаётся, как в `redact_for_jam`.
Проверка сервера идёт по последнему отчёту хоста, а браузер хоста выполняет накопленные команды пачкой. Поэтому сервер помечает команды участников (`jam_participant: true`), и браузер хоста проверяет их по своей текущей очереди (`_jamParticipantCommandAllowed`): удаление приватного элемента, очистка очереди с ними, добавление плейсхолдеров и полная очередь, где приватных элементов не столько же, сколько у хоста сейчас, не выполняются. Когда гость перестаёт управлять Jam (вышел или Jam исчез), плейсхолдеры удаляются из его очереди и не становятся его собственной очередью.
### 5. Документация и версия
- `docs/development.md`: новый раздел о синхронизации устройств, мосте и тестах.
- `docs/administration.md`: что видит пользователь.
- `CHANGELOG` v0.13.0. Версия `furumusic` поднята до 0.13.0 (минорная).
## Решения и отступления от плана
- **Номера миграций.** `m_0053` уже занят в этом же app (`src/user.rs`, `m_0053_local_approval_and_public_shares`), поэтому использованы `m_0054` и `m_0055`. Цепочка в `music/mod.rs` идёт от `m_0052`.
- **Таблица `furumusic__fed_podcast_relay`.** Это не модель подкастов, а непрозрачный кэш регистров контракта F1 (это разрешено пунктом «minimal lossless storage»). Без неё веб терял бы секции snapshot и не мог бы честно объявлять v4. В MR-W2 данные можно импортировать в нормальные таблицы.
- **Минимальная версия 2 при отсечке `listen_recorded`.** Веб работает только по `furumi/sync/2`, значит любой пир поддерживает хотя бы v2. Без этого события прослушивания в `PairRequest` к инвайтеру TUI 0.3 (инвайт без `p`, то есть версия 1) терялись бы навсегда: векторы только растут, а в snapshot прослушиваний нет. На отсечку подкастов (v4) это не влияет.
- **Jam в вебе.** Это внутренний механизм хаба между пользователями одного сервера, а не протокол `music_dht::jam`. Поэтому решения принимают функции F1 над wire-«тенью» очереди, а JSON-элементы переставляются по тому же правилу.
- **Мелкие исправления по ходу:**
- проверка переноса до смены владельца в хабе — раньше хаб переключался, даже если перенос потом падал;
- `queue_pos` больше не съезжает при пропуске битого элемента;
- поиск `content_id` в БД делается, только если его нет в JSON, — результат тот же;
- assert в `interop_tests` теперь принимает версию 3..=4.
- **`playback_rate`.** Поле зарезервировано и через мост веба не переносится. Веб отправляет `None`, что получатели читают как 1.0.
## Исправления по первому ревью
Все пять замечаний ревью подтвердились и исправлены отдельными коммитами с регрессионными тестами.
- **(high) Передача выпуска TUI → веб → TUI теряла позицию.** Ветка недоступного элемента в `_executeRemoteCommand` вызывала `_applyRemotePlaybackState` + `_pauseLocal`, а `_tickRemoteProgress` на активном устройстве время не ставит, поэтому `_devicePlaybackStatePayload` отдавал время старого `<audio>` (или 0). Теперь `_showUnplayableQueueItem(track, position)` выгружает прежний источник и хранит переданную позицию (также при восстановлении состояния, `_syncLocalPlaybackState` и `_playLocal`). `_devicePlaybackStatePayload` берёт `audio.currentTime` только для элемента, который реально загружен в `<audio>` (`_currentItemHasLocalAudio`). Поздний `timeupdate` после выгрузки аудио позицию не сбрасывает. Тесты: node (`transfer_state` с выпуском на 1200 с при `<audio>` на 95 с и на свежей странице → отчёт 1200 с, пауза, индекс 1; музыка по-прежнему отдаёт время `<audio>`), Rust (`podcast_queue_survives_server_browser_server_round_trip`: `position_secs` 1200 проходит пир → браузер → пир).
- **(medium) Бесконечная рекурсия при repeat «one» на неиграбельном текущем элементе.** `resume()` больше не вызывает `next()`, а переходит через `_skipUnplayableCurrentItem`; `next()` не применяет repeat «one» к элементу, который веб не может играть. Тест node: repeat `one`/`off`/`all` с единственным выпуском — без исключения, элемент и позиция остаются; с музыкой после выпуска — играет следующий трек; repeat `all` — переход к первому.
- **(medium) Гости Jam могли удалить приватные элементы хоста.** `restore_jam_command_payload` теперь отклоняет `queue_remove` приватного элемента и `queue_clear` очереди с приватными элементами (см. раздел Jam). Тест `jam_command_tests::participants_cannot_remove_or_clear_private_items`.
- **(low) Длительность приватного текущего элемента была видна гостю.** `redact_playback_state_for_jam` обнуляет `duration_seconds` (текущий элемент берётся из `track`, а без него — из `tracks[index]`). Тест `jam_command_tests::redacted_current_episode_has_no_duration`.
- **(low) Undo Metadata Repair для записей до `m_0054`.** `restore_deleted` сравнивает `to_jsonb(t) - 'queue_items_json'`, если в архиве нет этого ключа; колонка при восстановлении становится NULL, и чтение берёт `queue_json`. Изменённая после удаления строка по-прежнему отклоняется. Тест `undo_accepts_playback_archives_written_before_the_typed_queue` (ignored, нужна мигрированная БД).
## Исправления по повторному ревью
Все семь замечаний подтвердились (проверено по коду и сценариями ревьюера) и исправлены новыми коммитами с регрессионными тестами.
- **(medium) Веб выдумывал позицию 0 для выпуска, ставшего текущим без переданной позиции** (Next/автопереход на выпуск, `play_from_index` от другого браузера или гостя, Next/клик по выпуску при управлении TUI). 0 уходил на TUI как позиция передачи или как seek и записывался в прогресс явным действием. Исправлено: `position_unknown` в браузере и в состоянии хаба (`PlayerDevicePlaybackStateDto.position_unknown`), заполнение позиции и поколения из `furumusic__fed_podcast_relay` в `playback_state_from_browser_json` (передача, takeover, snapshot, команды пульта), команды `play_*`/`next`/`prev` на другой элемент помечают позицию неизвестной, `seek` и перезапуск — нет. Тесты: `commands_that_select_an_item_do_not_know_its_position`, `unknown_episode_position_resumes_from_the_progress_register`, `known_positions_and_music_never_read_the_progress_register`, Postgres `postgres_unknown_episode_position_and_rollback_cleanup` (передача на TUI и удалённый Next получают 1200 с и поколение 9), node «an episode reached without its position reports it as unknown, never as 0».
- **(medium) Проверка удаления/очистки приватных элементов гостем шла по устаревшему снимку хоста.** Исправлено пометкой `jam_participant` и проверкой в браузере хоста (см. Jam). Тесты: `participant_commands_reach_the_host_stamped`, node «the Jam host keeps its private items against stale participant commands» (move → remove в одной пачке оставляет выпуск; clear, добавление плейсхолдера и устаревшая полная очередь отклоняются).
- **(low) При repeat «all»/shuffle воспроизведение останавливалось на выпуске в конце очереди.** Исправлено в `playQueueIndex`. Тест node «repeat all and shuffle continue past a trailing unplayable item».
- **(low) Prev не уходил с переданного выпуска при позиции > 3 с, seek игнорировался.** Исправлено в `prev()`/`seek()`/`seekRelative()`. Тест node «prev and seek work on a handed-off episode».
- **(low) После выхода из Jam очередь хоста с плейсхолдерами становилась очередью гостя.** Исправлено `_dropJamPlaceholders` при выходе из управления Jam, а сервер не сохраняет плейсхолдеры в типизированную очередь (`StoredQueue::new`). Тесты: node «leaving a Jam drops the host placeholders from the guest queue», «the devices store drops placeholders…», Rust `stored_queue_never_keeps_jam_placeholders`.
- **(medium) Утверждение «откат на 0.12.x возможен» было неверным:** 0.12 падает на всей пачке операций, если в журнале есть подкастовая операция. Исправлено: шаг перед откатом описан в `docs/administration.md` («Rolling back to 0.12», `DELETE FROM furumusic__fed_sync_ops WHERE kind LIKE 'podcast\_%'`), тот же запрос (`DELETE_PODCAST_SYNC_OPS_SQL`) выполняет обратная операция `m_0055`. Postgres-тест разбирает журнал дословными типами 0.12.4: до очистки ошибка, после — читается, команды воспроизведения с `source` остаются.
- **(low) После отката и повторного обновления типизированная очередь могла восстановить не тот текущий элемент.** Исправлено сравнением `current_track_id` и `queue_position` (см. раздел 3). Тест `stored_queue_prefers_typed_value_only_while_legacy_ids_match` дополнен случаями «0.12 перешёл на другой трек той же очереди».
## Совместимость и версии
- `music-dht` 0.5.0 → **0.6.0**. **`Cargo.lock` и `[patch]`:** последний коммит этого MR, «Point frid deps at the fork branch», подключает неопубликованный frid из форка: в `[patch.crates-io]` в `Cargo.toml` `music-dht` указывают на `git = "https://gt.hexor.cy/Sanapach/frid.git", branch = "podcasts/contract"`, а в `Cargo.lock` у frid-крейтов (включая `federation-net`) стоит `source = "git+https://gt.hexor.cy/Sanapach/frid.git?branch=…#<sha>"`. После публикации крейтов на crates.io эти строки удаляются, и lock перегенерируется ещё раз.
- `furumusic` 0.12.4 → **0.13.0**.
- ALPN не меняется (`furumi/sync/2`).
- С пирами v3 (TUI 0.3.x, веб 0.12.x) музыка, плейлисты, лайки, история и playback только с музыкой работают как раньше, JSON для них побайтово тот же. Подкастовые операции, секции snapshot и playback с выпусками им не отправляются.
- БД: две новые миграции с обратными операциями. `queue_json`, `current_track_id` и `queue_position` по-прежнему пишутся.
- Откат на 0.12.x возможен **только после удаления подкастовых операций** из журнала: сервер 0.12 не разбирает их и не синхронизирует ни одно устройство, которое их ещё не получило. Перед запуском 0.12 остановить сервер и выполнить `DELETE FROM furumusic__fed_sync_ops WHERE kind LIKE 'podcast\_%';` (описано в `docs/administration.md`; обратная операция `m_0055` делает то же, но старый бинарник обратные операции не запускает). Таблицу relay и колонку `queue_items_json` можно оставить: 0.12 их не читает.
- Новые ключи браузерного JSON: `position_unknown` в состоянии устройства (только `true`, иначе отсутствует) и `jam_participant` в командах участников Jam. Старые браузеры их игнорируют. В wire-протокол они не попадают.
## Как проверено (macOS 26 / Darwin 25.5, arm64; rustc 1.100.0 и 1.97.0)
После исправлений по повторному ревью (ветка на `c1cd689`), `CARGO_TARGET_DIR=/Users/krypton/furumi/gitea/.targets/web-w1`, `music-dht` из `.cargo`-патча на frid-f1:
- `cargo fmt --all -- --check`: 20 диффов в `src/admin/mod.rs` (18), `src/agent/dedup.rs` (1), `src/jobs/inbox_process.rs` (1) — ровно те же есть на master, эти файлы не трогались. Мои файлы отформатированы.
- `cargo clippy --all-targets --message-format=short -- -D warnings`: на master уже падает. Набор диагностик (файл + сообщение) ветки **совпадает с master**: 80 на 1.100.0 и 75 на `cargo +1.97.0` (CI). Новая `type_complexity` в `metadata_fix.rs` исправлена псевдонимом типа.
- `cargo test --all-targets -- --skip real_transcodes_match_and_keep_distinct_bitrates`: **154 passed, 0 failed, 14 ignored** (было 149/13). Пропущенный тест требует ffmpeg и без него падает и на master. Каждый новый коммит отдельно проходил `cargo test` и node-тесты.
- `node --test tests/*.test.cjs`: **43 pass, 0 fail** (`tests/player_queue_sources.test.cjs` — 14 тестов production-методов плеера в `vm`; новые тесты на шаблоне до исправлений падают).
- PostgreSQL: временный контейнер `postgres:16-alpine` на случайном порту 127.0.0.1, БД мигрирована двумя запусками debug-сервера (`FURU_DATABASE_URL=…`; первый запуск на пустой БД паникует в планировщике после миграций — известная проблема master; `m_0054`, `m_0055` применились). Затем:
`FURU_DEVICE_SYNC_TEST_DATABASE_URL=… FURU_METADATA_FIX_TEST_DATABASE_URL=… cargo test --all-targets -- --ignored postgres_ undo_accepts_playback_archives_written_before_the_typed_queue`:
- `postgres_podcast_relay_gating_and_peer_versions` — ok;
- `postgres_unknown_episode_position_and_rollback_cleanup` (новый) — ok;
- `undo_accepts_playback_archives_written_before_the_typed_queue` — ok (в прошлом раунде не запускался);
- ещё два теста, попавшие под фильтр `postgres_` (`oidc::approval_tests…`, `admin::statistics…`), требуют других переменных окружения и к MR не относятся.
Контейнер удалён.
- Ранее (до повторного ревью): миграции на чистой БД проверены через `\d` и `information_schema`; ручная E2E-проверка в headless Chrome 157 через CDP (2 строки `.queue-track.unplayable`, у аудио нет `src`, `wire_track` выпуска после `_saveState()` побайтово равен исходному, ошибок JS нет).
## Ограничения
- Воспроизведение подкастов в вебе будет в MR-W2. Пока выпуски сохраняются, помечаются и пропускаются.
- В relay-таблице сеансы прослушивания копятся без предела, ограничивается только исходящий snapshot.
- Отказ удалённой команды (`SetState`) устройству ниже v4 возвращает 400, но в UI сообщение видно только при переносе через меню устройств: `sendCommand` ошибки не показывает.
- Позиция для выпуска с неизвестной позицией берётся из релейного регистра. Если операция прогресса от TUI ещё не дошла до сервера, будет взят более старый регистр (или 0, если регистра нет) — это ограничение того, что сервер знает; заметно только в окне до синхронизации.
- После перезагрузки страницы сохранённая позиция 0 для текущего выпуска считается неизвестной (флаг не сохраняется в `furumusic__playback_state`), и сервер берёт позицию из регистра.
- При shuffle, если выбран выпуск, поиск воспроизводимого элемента идёт от выбранного индекса в сторону текущего, затем по кругу; новой случайной выборки нет.
- Гонка «устаревший индекс» для команд гостя по **музыке** (удалить не тот трек после перемещения) осталась, как на master; защищены только приватные элементы.
- E2E в headless Chrome после исправлений по ревью не повторялся; поведение плеера проверено node-тестами production-методов, серверные пути — Rust- и Postgres-тестами. Реальный откат на бинарник 0.12 после очистки не запускался: вместо этого журнал разбирается дословными типами 0.12.4.
- С реальным TUI проверено только межклиентским прогоном в составе всего стека (веб 0.15.0 + TUI 0.5.0, см. «Межклиентская проверка»), а не на вершине этой ветки. Тест `localhost_tui_peer` не запускался. Не проверены Playwright `browser-*.cjs`, Linux и Windows.
- Уже есть на master, не связано с этим MR:
- `cargo fmt --check` и `clippy -D warnings` падают;
- при первом старте на пустой БД планировщик паникует до окончания миграций (повторный старт работает).
## Зависимости от других MR
- Зависит от **MR-F1** (frid, ветка `podcasts/contract`, `music-dht` 0.6.0: `music_dht::podcast`, `device_sync` v4). До публикации подключается через `[patch.crates-io]`.
- MR-W2 будет строиться на этом MR: `queue_items`, `podcast_relay`, `queue_items_json`.
- Ветка `Sanapach/furumi-web:podcasts/queue-source` → `Furumi/furumi-web:master` (база `9b92385`, вершина `4f17fee`). Последний коммит — «Point frid deps at the fork branch» (`4f17fee`, см. «Совместимость и версии»).
- Все двенадцать коммитов относятся к этому MR (база `origin/master`):
- `75c6702` Update music-dht to 0.6.0
- `b558cf3` Relay device-sync v4 and keep podcast queue items
- `c14ab8d` Document podcast queue support and release 0.13.0
- `4d0b352` Keep the episode position and skip unplayable items safely in the player
- `a9736e5` Keep Jam guests from removing or timing the host's private items
- `19139ea` Undo metadata deletions archived before the typed queue column
- `ab7202f` Note the podcast queue fixes in the changelog
- `d1be583` Resume unknown episode positions from progress, not 0
- `6f3ed4b` Check Jam participant commands against the host queue
- `3af0e8c` Keep a rollback to 0.12 safe for sync and the typed queue
- `a04a746` Note the review fixes in the changelog and docs
- `c1cd689` Test episode resume positions and rollback cleanup on PostgreSQL
- `4f17fee` Point frid deps at the fork branch
## Межклиентская проверка
Мост очереди, отсечка v4 и редакция Jam из этого MR проверены в составе всего стека: веб 0.15.0 (`0e985b4`) с TUI 0.5.0 (`409188b`), старые TUI 0.3.5 и веб 0.12.4, frid `9c82f6d`. Прогон шёл на macOS, ленты только с 127.0.0.1, PostgreSQL в одноразовом контейнере, браузер — headless Chrome через CDP. Полная таблица — в MR-W2.
- Перенос очереди с выпуском веб ↔ TUI: выпуск, очередь, позиция и пауза сохраняются (S3) — pass.
- Старые пиры (S4): веб 0.12.4 в группе с новым TUI и TUI 0.3.5 в группе с новым вебом. Подкастовых данных у них нет (0 совпадений в `pg_dump` и файлах), плейлисты синхронизируются, перенос с выпуском отклоняется «needs an update», отправитель продолжает играть — pass.
- Jam в вебе (S5): гость видит только «Private item · hidden by its owner», в его ответах API нет данных выпусков — pass.
- Не прогонялось: Jam с хостом-TUI и гостем-вебом (веб не поддерживает федеративный Jam).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
The podcast contract and device-sync protocol v4 live in music-dht 0.6.
Cargo.lock currently resolves it from a local patch of the frid branch
podcasts/contract and must be regenerated against the published crate.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Use the shared music_dht::device_sync types instead of private copies
(byte-identical for v3 content, checked against the 0.12.x types and a
golden fixture) and announce protocol 4, because every v4 element is
kept:
- podcast operations stay in the operation log and are relayed only to
peers that reported v4; their registers and the podcast snapshot
sections are merged with the shared rules into an opaque relay table
and returned in this server's snapshots (m_0055);
- the browser bridge carries PlaybackTrack.source: items that are not
library tracks keep the verbatim wire item, so podcast episodes and
Jam placeholders survive the round trip; the player labels and skips
them instead of dropping them;
- the typed queue is persisted in queue_items_json next to queue_json,
which is still written for rollback (m_0054).
Peer versions come from self-reports (profile_protocol_version); relayed
profiles only raise them and DeviceProfileSet no longer stores this
server's constant. Invites carry the inviter's version and a
DeviceProfileSet announces v4 once. Handoffs of a podcast queue to a
device below v4 are refused with an update message, and its playback
commands are ignored while the queue has podcast items. Jam guests see
podcast items as private placeholders, which are mapped back on their
commands.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The web player only knows a podcast episode's position from a handoff or
a seek. When Next, auto-advance, a click or a play command makes an
episode current, it now reports `position_unknown` instead of 0, and the
server takes the resume position (and the register generation) from the
relayed progress register before it hands the state to another device.
Remote Next/Prev/play commands to a device do the same.
Next with repeat all or shuffle wraps past a trailing unplayable item
instead of stopping on it. Prev leaves an unplayable item instead of
"restarting" it, and seeking such an item moves its kept position.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The server checked a participant's queue_remove/queue_clear against the
host state of the last report, but the host browser runs its pending
commands in one batch: after a move, a checked index can name a private
item. Participant commands are now stamped `jam_participant`, and the
host browser refuses to remove, clear, add or bring back its private
items for them, judged on the queue it is about to change.
A guest that stops controlling a Jam drops the host's private
placeholders from its own queue, so they are not saved or relayed as
the guest's queue.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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>
The ignored device-sync PostgreSQL test now also covers a handoff and a
remote Next onto an episode with an unknown position (the relayed
progress register supplies 1200 s and its generation), and checks that
0.12's operation types fail on a relayed podcast operation and read the
log again after the documented cleanup statement, which the m_0055
backwards operation now shares.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
sanapach
changed title from Podcasts/queue source to Очередь без потерь в вебе: общие DTO, явный source и device-sync v4 с отсечкой (MR-W1)2026-11-20 13:41:27 +00:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Что сделано
MR-W1 из плана подкастов (
PODCASTS_PLAN.md, решения Р4, Р5, Р6 для веба). Подкасты в UI, RSS и хранилище подкастов будут в MR-W2. Здесь веб перестаёт терять элементы очереди и состояние подкастов, которые проходят через него, и начинает объявлять протокол синхронизации устройств v4.1. Общие DTO вместо приватных копий
src/federation/devices.rs:InviteWire,DeviceProfileWire,SyncedFedTrack,PlaybackTrack,PlaybackStateWire,SyncOpWire,SyncOpPayload,SyncSnapshot*,WireMessage. Вместо них используетсяmusic_dht::device_sync. Вспомогательные функции приглашений и чтения/записи строк тоже берутся изmusic_dht.wire_compat_tests.rsхранит дословную копию типов 0.12.4;fixtures/v3_hello.golden.json(все v3-операции, все секции snapshot, playback с координацией) — эталон формы master;pв инвайте иprotocol_versionвdevice_profile_set;kindподкастовой операции и теряютsourceу выпуска.2. Очередь без потерь: явный
sourceв мосте браузер ↔ wiresrc/player/queue_items.rs. Каждый элемент, который не является треком библиотеки, превращается во внешний элемент браузера: поля для показа,source(PlaybackSource) иwire_track(исходныйPlaybackTrackбез изменений). Это выпуски подкастов, Private-плейсхолдеры Jam и неразрешённая музыка федерации.wire_track. Поэтому выпуск проходит путь пир → сервер → браузер → сервер → пир без изменений.id, удалён.queue_posбольше не сдвигается.<audio>или нулём;position_unknown: true, а сервер перед передачей на другое устройство берёт позицию возобновления из релейного регистра прогресса (resume_position_ms(), без регистра — 0) и поднимаетprogress_generationэлемента до поколения регистра. Так же сервер поступает с командамиplay_track/play_from_index/next/prev, которые веб отправляет на TUI как пульт;3. Типизированное хранение очереди
m_0054_add_typed_playback_queueдобавляет колонкуfurumusic__playback_state.queue_items_json JSONB.IF NOT EXISTS, у миграции есть обратная операция.{version: 1, position, items: [{kind: library, track_id} | {kind: external, track: PlaybackTrack}], legacy_queue, legacy_current_track_id, legacy_queue_position}.queue_jsonпо-прежнему записывается, чтобы можно было откатиться на старую версию.queue_json,current_track_id,queue_position) совпадают со строкой. Иначе (откат на старую версию, запись только старым кодом, в том числе переход старого релиза на другой трек той же очереди) берутся старые колонки.private) в собственную очередь пользователя не сохраняются никогда.library_cleanup);m_0054(в архиве нет ключаqueue_items_json), сравнивает строку без этой колонки и по-прежнему работает./api/player/stateполучил необязательные поляqueue_itemsиqueue_items_position. Старые клиенты работают как раньше.4. Протокол v4 и отсечка
Почему веб объявляет v4.
furumusic__fed_podcast_relay(миграцияm_0055):merge_*изmusic_dht::podcast;podcast_snapshot_budget;PROTOCOL_VERSION = 4привязана кDEVICE_SYNC_PROTOCOL_VERSIONпроверкой при компиляции.Что отправляется пиру.
ops_for_peerпрячет неподдерживаемые kind ещё в SQL, чтобы курсор не застревал. Финальная проверка —op_allowed_for_peer.SyncSnapshot::for_peer.playback_allowed_for_peer.PairRequestограничивается поInviteWire::inviter_protocol_version(). Инвайты веба передаютp = 4.Версии пиров.
profile, его собственная запись вdevices,DeviceProfileSet) обрабатывается черезprofile_protocol_version. Версии в профилях, переданных другими устройствами, — черезrelayed_protocol_version: они только повышают сохранённую.DeviceProfileSetвapply_opиanswer_pairing.DeviceProfileSetсprotocol_version.Перенос и команды.
SetStateиActiveChangedот пира ниже v4 игнорируются, пока в очереди есть выпуски.Jam. Гости видят состояние хоста через
redact_for_jam: выпуски показываются как приватные элементы. Команды гостя с выпусками отклоняются (jam_command_allowed). Если гость присылает полную очередь, плейсхолдеры возвращаются на место хостовых элементов черезrestore_jam_private_items. Попытки удалить, продублировать или подложить приватный элемент отклоняются:queue_removeпо индексу приватного элемента хоста (и индекс не целым числом, пока в очереди хоста есть приватные элементы: браузер хоста выполняетNumber(index));queue_clear, пока в очереди хоста есть приватные элементы.Перемещать приватный элемент (
queue_move) гостю можно. Если текущий элемент хоста приватный, гость не видит его длительность (duration_seconds = 0); позиция остаётся, как вredact_for_jam.Проверка сервера идёт по последнему отчёту хоста, а браузер хоста выполняет накопленные команды пачкой. Поэтому сервер помечает команды участников (
jam_participant: true), и браузер хоста проверяет их по своей текущей очереди (_jamParticipantCommandAllowed): удаление приватного элемента, очистка очереди с ними, добавление плейсхолдеров и полная очередь, где приватных элементов не столько же, сколько у хоста сейчас, не выполняются. Когда гость перестаёт управлять Jam (вышел или Jam исчез), плейсхолдеры удаляются из его очереди и не становятся его собственной очередью.5. Документация и версия
docs/development.md: новый раздел о синхронизации устройств, мосте и тестах.docs/administration.md: что видит пользователь.CHANGELOGv0.13.0. Версияfurumusicподнята до 0.13.0 (минорная).Решения и отступления от плана
m_0053уже занят в этом же app (src/user.rs,m_0053_local_approval_and_public_shares), поэтому использованыm_0054иm_0055. Цепочка вmusic/mod.rsидёт отm_0052.furumusic__fed_podcast_relay. Это не модель подкастов, а непрозрачный кэш регистров контракта F1 (это разрешено пунктом «minimal lossless storage»). Без неё веб терял бы секции snapshot и не мог бы честно объявлять v4. В MR-W2 данные можно импортировать в нормальные таблицы.listen_recorded. Веб работает только поfurumi/sync/2, значит любой пир поддерживает хотя бы v2. Без этого события прослушивания вPairRequestк инвайтеру TUI 0.3 (инвайт безp, то есть версия 1) терялись бы навсегда: векторы только растут, а в snapshot прослушиваний нет. На отсечку подкастов (v4) это не влияет.music_dht::jam. Поэтому решения принимают функции F1 над wire-«тенью» очереди, а JSON-элементы переставляются по тому же правилу.queue_posбольше не съезжает при пропуске битого элемента;content_idв БД делается, только если его нет в JSON, — результат тот же;interop_testsтеперь принимает версию 3..=4.playback_rate. Поле зарезервировано и через мост веба не переносится. Веб отправляетNone, что получатели читают как 1.0.Исправления по первому ревью
Все пять замечаний ревью подтвердились и исправлены отдельными коммитами с регрессионными тестами.
_executeRemoteCommandвызывала_applyRemotePlaybackState+_pauseLocal, а_tickRemoteProgressна активном устройстве время не ставит, поэтому_devicePlaybackStatePayloadотдавал время старого<audio>(или 0). Теперь_showUnplayableQueueItem(track, position)выгружает прежний источник и хранит переданную позицию (также при восстановлении состояния,_syncLocalPlaybackStateи_playLocal)._devicePlaybackStatePayloadберётaudio.currentTimeтолько для элемента, который реально загружен в<audio>(_currentItemHasLocalAudio). Позднийtimeupdateпосле выгрузки аудио позицию не сбрасывает. Тесты: node (transfer_stateс выпуском на 1200 с при<audio>на 95 с и на свежей странице → отчёт 1200 с, пауза, индекс 1; музыка по-прежнему отдаёт время<audio>), Rust (podcast_queue_survives_server_browser_server_round_trip:position_secs1200 проходит пир → браузер → пир).resume()больше не вызываетnext(), а переходит через_skipUnplayableCurrentItem;next()не применяет repeat «one» к элементу, который веб не может играть. Тест node: repeatone/off/allс единственным выпуском — без исключения, элемент и позиция остаются; с музыкой после выпуска — играет следующий трек; repeatall— переход к первому.restore_jam_command_payloadтеперь отклоняетqueue_removeприватного элемента иqueue_clearочереди с приватными элементами (см. раздел Jam). Тестjam_command_tests::participants_cannot_remove_or_clear_private_items.redact_playback_state_for_jamобнуляетduration_seconds(текущий элемент берётся изtrack, а без него — изtracks[index]). Тестjam_command_tests::redacted_current_episode_has_no_duration.m_0054.restore_deletedсравниваетto_jsonb(t) - 'queue_items_json', если в архиве нет этого ключа; колонка при восстановлении становится NULL, и чтение берётqueue_json. Изменённая после удаления строка по-прежнему отклоняется. Тестundo_accepts_playback_archives_written_before_the_typed_queue(ignored, нужна мигрированная БД).Исправления по повторному ревью
Все семь замечаний подтвердились (проверено по коду и сценариями ревьюера) и исправлены новыми коммитами с регрессионными тестами.
play_from_indexот другого браузера или гостя, Next/клик по выпуску при управлении TUI). 0 уходил на TUI как позиция передачи или как seek и записывался в прогресс явным действием. Исправлено:position_unknownв браузере и в состоянии хаба (PlayerDevicePlaybackStateDto.position_unknown), заполнение позиции и поколения изfurumusic__fed_podcast_relayвplayback_state_from_browser_json(передача, takeover, snapshot, команды пульта), командыplay_*/next/prevна другой элемент помечают позицию неизвестной,seekи перезапуск — нет. Тесты:commands_that_select_an_item_do_not_know_its_position,unknown_episode_position_resumes_from_the_progress_register,known_positions_and_music_never_read_the_progress_register, Postgrespostgres_unknown_episode_position_and_rollback_cleanup(передача на TUI и удалённый Next получают 1200 с и поколение 9), node «an episode reached without its position reports it as unknown, never as 0».jam_participantи проверкой в браузере хоста (см. Jam). Тесты:participant_commands_reach_the_host_stamped, node «the Jam host keeps its private items against stale participant commands» (move → remove в одной пачке оставляет выпуск; clear, добавление плейсхолдера и устаревшая полная очередь отклоняются).playQueueIndex. Тест node «repeat all and shuffle continue past a trailing unplayable item».prev()/seek()/seekRelative(). Тест node «prev and seek work on a handed-off episode»._dropJamPlaceholdersпри выходе из управления Jam, а сервер не сохраняет плейсхолдеры в типизированную очередь (StoredQueue::new). Тесты: node «leaving a Jam drops the host placeholders from the guest queue», «the devices store drops placeholders…», Ruststored_queue_never_keeps_jam_placeholders.docs/administration.md(«Rolling back to 0.12»,DELETE FROM furumusic__fed_sync_ops WHERE kind LIKE 'podcast\_%'), тот же запрос (DELETE_PODCAST_SYNC_OPS_SQL) выполняет обратная операцияm_0055. Postgres-тест разбирает журнал дословными типами 0.12.4: до очистки ошибка, после — читается, команды воспроизведения сsourceостаются.current_track_idиqueue_position(см. раздел 3). Тестstored_queue_prefers_typed_value_only_while_legacy_ids_matchдополнен случаями «0.12 перешёл на другой трек той же очереди».Совместимость и версии
music-dht0.5.0 → 0.6.0.Cargo.lockи[patch]: последний коммит этого MR, «Point frid deps at the fork branch», подключает неопубликованный frid из форка: в[patch.crates-io]вCargo.tomlmusic-dhtуказывают наgit = "https://gt.hexor.cy/Sanapach/frid.git", branch = "podcasts/contract", а вCargo.lockу frid-крейтов (включаяfederation-net) стоитsource = "git+https://gt.hexor.cy/Sanapach/frid.git?branch=…#<sha>". После публикации крейтов на crates.io эти строки удаляются, и lock перегенерируется ещё раз.furumusic0.12.4 → 0.13.0.furumi/sync/2).queue_json,current_track_idиqueue_positionпо-прежнему пишутся.DELETE FROM furumusic__fed_sync_ops WHERE kind LIKE 'podcast\_%';(описано вdocs/administration.md; обратная операцияm_0055делает то же, но старый бинарник обратные операции не запускает). Таблицу relay и колонкуqueue_items_jsonможно оставить: 0.12 их не читает.position_unknownв состоянии устройства (толькоtrue, иначе отсутствует) иjam_participantв командах участников Jam. Старые браузеры их игнорируют. В wire-протокол они не попадают.Как проверено (macOS 26 / Darwin 25.5, arm64; rustc 1.100.0 и 1.97.0)
После исправлений по повторному ревью (ветка на
c1cd689),CARGO_TARGET_DIR=/Users/krypton/furumi/gitea/.targets/web-w1,music-dhtиз.cargo-патча на frid-f1:cargo fmt --all -- --check: 20 диффов вsrc/admin/mod.rs(18),src/agent/dedup.rs(1),src/jobs/inbox_process.rs(1) — ровно те же есть на master, эти файлы не трогались. Мои файлы отформатированы.cargo clippy --all-targets --message-format=short -- -D warnings: на master уже падает. Набор диагностик (файл + сообщение) ветки совпадает с master: 80 на 1.100.0 и 75 наcargo +1.97.0(CI). Новаяtype_complexityвmetadata_fix.rsисправлена псевдонимом типа.cargo test --all-targets -- --skip real_transcodes_match_and_keep_distinct_bitrates: 154 passed, 0 failed, 14 ignored (было 149/13). Пропущенный тест требует ffmpeg и без него падает и на master. Каждый новый коммит отдельно проходилcargo testи node-тесты.node --test tests/*.test.cjs: 43 pass, 0 fail (tests/player_queue_sources.test.cjs— 14 тестов production-методов плеера вvm; новые тесты на шаблоне до исправлений падают).postgres:16-alpineна случайном порту 127.0.0.1, БД мигрирована двумя запусками debug-сервера (FURU_DATABASE_URL=…; первый запуск на пустой БД паникует в планировщике после миграций — известная проблема master;m_0054,m_0055применились). Затем:FURU_DEVICE_SYNC_TEST_DATABASE_URL=… FURU_METADATA_FIX_TEST_DATABASE_URL=… cargo test --all-targets -- --ignored postgres_ undo_accepts_playback_archives_written_before_the_typed_queue:postgres_podcast_relay_gating_and_peer_versions— ok;postgres_unknown_episode_position_and_rollback_cleanup(новый) — ok;undo_accepts_playback_archives_written_before_the_typed_queue— ok (в прошлом раунде не запускался);postgres_(oidc::approval_tests…,admin::statistics…), требуют других переменных окружения и к MR не относятся.Контейнер удалён.
\dиinformation_schema; ручная E2E-проверка в headless Chrome 157 через CDP (2 строки.queue-track.unplayable, у аудио нетsrc,wire_trackвыпуска после_saveState()побайтово равен исходному, ошибок JS нет).Ограничения
SetState) устройству ниже v4 возвращает 400, но в UI сообщение видно только при переносе через меню устройств:sendCommandошибки не показывает.furumusic__playback_state), и сервер берёт позицию из регистра.localhost_tui_peerне запускался. Не проверены Playwrightbrowser-*.cjs, Linux и Windows.cargo fmt --checkиclippy -D warningsпадают;Зависимости от других MR
podcasts/contract,music-dht0.6.0:music_dht::podcast,device_syncv4). До публикации подключается через[patch.crates-io].queue_items,podcast_relay,queue_items_json.Sanapach/furumi-web:podcasts/queue-source→Furumi/furumi-web:master(база9b92385, вершина4f17fee). Последний коммит — «Point frid deps at the fork branch» (4f17fee, см. «Совместимость и версии»).origin/master):75c6702Update music-dht to 0.6.0b558cf3Relay device-sync v4 and keep podcast queue itemsc14ab8dDocument podcast queue support and release 0.13.04d0b352Keep the episode position and skip unplayable items safely in the playera9736e5Keep Jam guests from removing or timing the host's private items19139eaUndo metadata deletions archived before the typed queue columnab7202fNote the podcast queue fixes in the changelogd1be583Resume unknown episode positions from progress, not 06f3ed4bCheck Jam participant commands against the host queue3af0e8cKeep a rollback to 0.12 safe for sync and the typed queuea04a746Note the review fixes in the changelog and docsc1cd689Test episode resume positions and rollback cleanup on PostgreSQL4f17feePoint frid deps at the fork branchМежклиентская проверка
Мост очереди, отсечка v4 и редакция Jam из этого MR проверены в составе всего стека: веб 0.15.0 (
0e985b4) с TUI 0.5.0 (409188b), старые TUI 0.3.5 и веб 0.12.4, frid9c82f6d. Прогон шёл на macOS, ленты только с 127.0.0.1, PostgreSQL в одноразовом контейнере, браузер — headless Chrome через CDP. Полная таблица — в MR-W2.pg_dumpи файлах), плейлисты синхронизируются, перенос с выпуском отклоняется «needs an update», отправитель продолжает играть — pass.🤖 Generated with Claude Code
Podcasts/queue sourceto Очередь без потерь в вебе: общие DTO, явный source и device-sync v4 с отсечкой (MR-W1)View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.