Подкасты в FRID: SQLite-хранилище PodcastStore, импорт прототипа и TrackItem.podcast (MR-F2) #2

Merged
ab merged 8 commits from sanapach/frid:podcasts/store into main 2026-11-20 13:51:51 +00:00
Member

Серия «Подкасты»: 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 и зависимости — в разделе зависимостей ниже.

Что сделано

Реализовано решение Р3 для SQLite-клиентов: новый модуль furumi_library::podcasts с PodcastStore. Это эталонное хранилище контракта подкастов из music_dht::podcast (MR-F1). Его будет использовать TUI (MR-T2).

  • Отдельный файл podcasts.sqlite3 (PODCAST_DB_FILE). Путь передаёт клиент. Включены WAL, внешние ключи и busy timeout 5 с.

  • Миграции по PRAGMA user_version. Каждая выполняется в отдельной транзакции BEGIN IMMEDIATE и заново читает версию, поэтому повторное открытие и одновременный запуск нескольких процессов безопасны.

    • v1 — схема прототипа из исходного PR, перенесена дословно.
    • v2 — новая модель. Таблицы прототипа переименовываются в legacy_podcasts / legacy_podcast_episodes, а не удаляются, и их данные импортируются.
    • Файл от более новой версии Furumi или чужой файл (например, по ошибке переданный library.db) отклоняется до любой записи, включая переключение в WAL. Файл остаётся побайтно неизменным.
  • Импорт прототипа.

    • Каждая лента становится подкастом. podcast_id вычисляется по каноническому URL функциями F1.
    • Для каждой ленты создаётся регистр подписки: подписан, поколение 0, hlc = added_at, op_id = legacy-import:<id>. Подписка приватная.
    • Невалидные URL и непригодные выпуски попадают в legacy_quarantine, исходные строки остаются в legacy_*.
    • Идентификаторы выпусков вычисляются по правилу идентичности F1.
    • Прототип хранил выпуск без GUID отдельной строкой на каждый URL вложения. Строки одного такого выпуска (та же секунда публикации, то же нормализованное название и та же ссылка или её отсутствие) схлопываются в самую новую. Остальные попадают в карантин как «duplicate episode».
    • Импортированные выпуски без GUID считаются предварительными. Первое обновление RSS, в котором они есть, переводит их на идентификатор, который даёт текущая лента (подробнее ниже).
    • ETag, Last-Modified, время проверки, ошибка и кэш обложки переносятся в локальное служебное состояние (podcast_fetch_state).
  • Таблицы. Подкасты (метаданные канала), алиасы лент, сезоны (вычисляются по выпускам), выпуски, регистры подписки, публикации и прогресса, сеансы прослушивания (G-set) и локальное служебное состояние проверок (podcast_fetch_state), которое никогда не попадает в синхронизацию.

  • Локальные действия. Каждое действие применяет операцию к хранилищу и возвращает её (PodcastLocalOp) для журнала синхронизации клиента:

    • subscribe, unsubscribe (прогресс и история сохраняются), set_shared;
    • start_session, checkpoint (поколение не меняется), seek, restart, complete_session, mark_played, mark_unplayed (поколение повышается через explicit_generation);
    • record_listen_session.

    Отметку операции (op_id, устройство, hlc) выдаёт журнал клиента через трейт StampSource.

  • Синхронизация.

    • apply_remote_op обрабатывает все пять видов podcast_*.
    • fill_snapshot / export_snapshot формируют секции snapshot с ограничением по F1 (bound_podcast_state_to).
    • apply_snapshot объединяет полученные секции.
    • Локальные действия, принятые операции и snapshot проходят один путь кода: материализаторы SyncOpWire::podcast_* и функции слияния F1.
  • Обновление RSS (apply_feed).

    • Обновляет метаданные канала и выпусков, включая URL аудио. Идентификаторы выпусков сохраняются по правилу F1, с учётом выпусков, полученных через синхронизацию.
    • Предварительные импортированные выпуски без прогресса и сеансов переводятся на идентификатор текущей ленты. Перевод делается в две фазы. Сопоставление идёт по вложению, затем по ссылке, затем по дате и названию; GUID при этом не учитывается. Персональные данные при этом не переносятся, потому что их у таких выпусков нет.
    • Если этот идентификатор уже занят выпуском, который остаётся (например, строкой, созданной удалённой операцией до первого обновления), предварительный выпуск — дубль элемента ленты, и он удаляется. То же, когда legacy_guid оказывается настоящим GUID элемента, а GUID-идентификатор уже занят.
    • Выпуски, пропавшие из ленты, сохраняются.
    • Постоянный редирект и itunes:new-feed-url превращаются в алиасы. Операция podcast_feed_aliases_added создаётся только если набор алиасов изменился.
    • Подписку, публикацию, прогресс и сеансы обновление не трогает.
  • Служебное состояние проверок. Все записи (record_fetch_*, set_cover_cache) читают и пишут строку под одной блокировкой в одной транзакции BEGIN IMMEDIATE. Параллельные записи из нескольких потоков или процессов не теряют ни столбцы, ни приращения счётчика ошибок.

  • Запросы для UI. Список подкастов (подписанные или все, со счётчиками непрослушанных), сезоны, выпуски (фильтр по сезону и статусу, поиск по тексту с Unicode-нормализацией, сортировка по дате или номеру, постраничный вывод), позиция продолжения, episode_ref / episode_track для очереди, история прослушиваний, служебное состояние проверок для планировщика (podcasts_due_for_refresh).

  • TrackItem.podcast: Option<PodcastEpisodeRef>. Добавлены TrackItem::podcast_episode, is_podcast, podcast_episode_ref.

    • Идентичность выпуска в очереди задаёт только явный источник TrackItem.podcast (EpisodeId). Никакого зарезервированного диапазона отрицательных id нет (требования §4, §10.2).

    • id, release_id и id исполнителя у всех выпусков равны фиксированному маркеру TrackItem::NOT_A_LIBRARY_ROW = −1. Это то же соглашение «не строка библиотеки», что у ожидающих федеративных треков. Маркер не несёт идентичности, общий для всех выпусков и не декодируется. Он лишь не даёт старому музыкальному коду (id >= 0, release_id < 0) принять выпуск за трек, релиз или исполнителя библиотеки с id 0.

    • TrackItem::key() -> TrackItemKey — типизированная идентичность источника элемента (Hash/Eq/Ord, Display со стабильной строкой):

      • Library(id) → lib:123 — строка библиотеки (id >= 0);
      • Federated { owner, item_id } → fed:<owner>:<item_id> — федеративный трек не из библиотеки; его отрицательный id — счётчик процесса и в ключ не входит (та же форма, что fed: в track_key furumi-tui);
      • PodcastEpisode(EpisodeId) → ep:<episode id>, например ep:ep1:…;
      • Transient(id) → tmp:-5 — элемент без библиотечной строки и без явного источника; furumi-library такие не создаёт.

      Приоритет: podcast → неотрицательный id → fed → Transient.

    • В rustdoc, README, ARCHITECTURE.md и PODCASTS.md записано: выпуск идентифицируется только TrackItem.podcast / ep: (в протоколе — PlaybackSource) и никогда не ключуется по id; ключ вида local:{id} склеил бы все выпуски в один. У TrackItemKey нет эквивалентности по content id: ожидающий федеративный трек (fed:) и его импортированная копия (lib:) различаются. Поэтому клиенты, которые сопоставляют музыку сначала по content id (как track_key в furumi-tui), так и делают дальше и добавляют ветку для подкастов перед любым откатом на id.

    • TrackItem::from_playback_track(&PlaybackTrack) -> PlaybackItem — преобразование полученного элемента воспроизведения без копирования wire-id. В F1 у выпуска и у приватной заглушки Jam id и release_id равны 0. PlaybackItem::PodcastEpisode(Box<TrackItem>) строится через TrackItem::podcast_episode (маркеры −1, ключ ep:) независимо от устаревших полей отображения; PlaybackItem::Private — неиграемая заглушка без TrackItem и без идентичности; PlaybackItem::Music оставляет музыку клиентскому пути (content id, затем fed).

    • В rustdoc TrackItem::podcast_episode перечислены отличия от wire-формы F1: id −1 вместо 0, release_year — год публикации (на проводе None), audio_format — None (MIME остаётся в ссылке).

    • Запросы библиотеки по-прежнему возвращают только музыку, схема library.db не изменилась. Музыкальный код обязан проверять is_podcast.

  • Документация. README крейта, ARCHITECTURE.md, новый раздел «SQLite reference store» в PODCASTS.md (схема и инварианты), CHANGELOG.md.

Исправления по ревью

  1. Идентификаторы импортированных выпусков без GUID (средняя важность, подтверждено).
    • Проблема. Если у такого выпуска менялся URL вложения, устаревшие строки прототипа делали ссылку и пару «дата + название» неуникальными. Тогда выпуск получал id, которого новое устройство никогда не вычислит. После синхронизации прогресс нового устройства оказывался на скрытом выпуске.
    • Исправление. Схлопывание дублей при импорте и перевод предварительных выпусков на идентификатор текущей ленты при первом обновлении (см. выше).
  2. TrackItem::podcast_episode с id 0 (средняя важность, подтверждено по коду furumi-tui: apply_queue_refresh, track_key, release_id < 0).
    • Проблема. Клиенты считали каждый выпуск треком библиотеки с id 0: удаляли его из очереди при обновлении библиотеки, а ключи всех выпусков совпадали (local:0).
    • Первое исправление (e627be5). Отрицательный id для каждого выпуска из зарезервированного диапазона ниже PODCAST_TRACK_ID_MAX, вычисляемый из дайджеста EpisodeId.
    • Замена (06ac369). Это и есть «магический диапазон отрицательных id», который требования (§4, §10.2) запрещают в общем контракте, а furumi-library — общий код FRID. TrackItem::podcast_track_id и PODCAST_TRACK_ID_MAX удалены. Выпуски получают фиксированный маркер −1 (id, release_id, id исполнителя), а идентичность — только из TrackItem.podcast через TrackItem::key() / TrackItemKey. Старые проверки id < 0 / release_id < 0 по-прежнему пропускают выпуски; код, который откатывается на id как ключ (track_key в furumi-tui, local:{id}), должен проверять выпуск (ep:) до этого отката (рекомендация уточнена в п. 5).
  3. Гонка в update_fetch_state (низкая важность, подтверждено).
    • Проблема. Чтение и запись шли под двумя разными захватами мьютекса, поэтому параллельные вызовы могли затереть друг друга.
    • Исправление. Одна блокировка и одна транзакция.

Повторное ревью

  1. Заблокированный перевод оставлял вечный дубль выпуска (средняя важность, подтверждено; коммит b8d8b53).
    • Проблема. Устройство A мигрирует базу прототипа и до первого обновления RSS применяет операцию прогресса нового устройства B. Появляется строка source = 'sync' с id текущей ленты. При обновлении предварительный выпуск сопоставлялся с тем же элементом, но его перевод блокировался, и он навсегда оставался второй копией с in_feed = 0, видимой в episodes() и счётчиках. Это нарушало требование §4: выпуски не должны дублироваться.
    • Исправление. Если цель занята выпуском, который остаётся, предварительный выпуск удаляется: прогресса и сеансов у него нет, а его метаданные всё равно перезаписал бы элемент ленты. Удалённый дубль освобождает свой id для других переводов. То же в rekey_legacy_guids, когда GUID-идентификатор уже занят. Удаление дополнительно защищено условием «legacy_guid задан, нет прогресса и сеансов». Сезоны пересчитываются, как и раньше, в конце apply_feed.
    • Тесты. remote_progress_before_the_first_refresh_leaves_no_duplicate_episode (точный порядок из ревью: операция B до первого обновления A; после каждого из двух обновлений одна строка «Pilot» с id ленты и позицией B), remote_progress_on_the_guid_id_removes_the_imported_copy (путь через legacy_guid). Ожидание в first_refresh_rekeys_provisional_imported_guidless_episodes уточнено: устаревшая строка того же элемента, которую при первом обновлении нельзя было сопоставить, удаляется вторым, когда остаётся единственным предварительным выпуском и её ссылка указывает на этот элемент. Все три теста падают на прежнем коде.
  2. Слишком широкая рекомендация про TrackItem::key (низкая важность, подтверждено по furumi-tui state.rs:2179-2186, app/mod.rs:3068-3117, только чтение; коммит d2530dc).
    • Проблема. Документация требовала сопоставлять всё по TrackItem::key. Но у ключа нет эквивалентности по content id, а обновление очереди в TUI заменяет ожидающий fed-элемент его библиотечной копией именно по content id. Буквальное следование сломало бы эту замену.
    • Исправление. Рекомендация сужена (см. выше): ключ — идентичность источника; выпуск никогда не ключуется по id; музыкальное сопоставление по content id остаётся, в него добавляется ветка подкастов перед откатом на id. Rustdoc, README, ARCHITECTURE.md, PODCASTS.md и CHANGELOG.md обновлены.
  3. Wire-id 0 у выпусков и приватных заглушек (низкая важность, подтверждено; коммит d2530dc).
    • Проблема. Маркер −1 защищал только элементы, созданные через TrackItem::podcast_episode. F1 передаёт выпуск и приватную заглушку с id = 0 и release_id = 0; клиент, копирующий поля (как to_track_item в furumi-tui), получил бы «релиз 0», а все заглушки совпали бы по lib:0.
    • Исправление. TrackItem::from_playback_track / PlaybackItem (см. выше) и документация: wire-id подкастов и заглушек равны 0 и не копируются. Формулировка «display fields mirror» исправлена. Тест received_playback_tracks_never_copy_wire_ids.

Решения и отступления от плана

  • В контракте F1 пять видов операций, а не четыре: добавилась podcast_feed_aliases_added. Обрабатываются все пять.
  • В схеме прототипа нет данных о прослушивании и позиции: позиция жила только в памяти (проверены store.rs, mod.rs, app/podcast_runtime.rs). Поэтому импорт не создаёт регистров прогресса, и параметр с id устройства не нужен. Импортированные подписки доходят до других устройств через snapshot.
  • Прототип записывал URL вложения в guid, когда у выпуска не было GUID. Такие строки импортируются как выпуски без GUID и считаются предварительными до первого обновления RSS. Исходное значение хранится в episodes.legacy_guid. Если обновление покажет это значение как настоящий GUID, выпуск получает GUID-идентификатор. Если выпуск сопоставлен с элементом ленты по вложению, ссылке или дате и названию, он получает идентификатор этого элемента. И то и другое — только при отсутствии у выпуска прогресса и сеансов.
  • Дубли при импорте схлопываются, только если совпадают и секунда публикации, и нормализованное название, и ссылка. Одной общей ссылки (например, домашней страницы шоу) недостаточно, чтобы не склеить разные выпуски. Остальные случаи исправляет первое обновление RSS.
  • Для пустого файла миграция тоже идёт через v1 (по плану: миграция 1 — схема PR). Поэтому таблицы legacy_* существуют и пустые.
  • У ожидающих федеративных треков ключ — (owner, item_id) из TrackItem.fed, а не отрицательный id: id у них — счётчик процесса (в furumi-tui ещё и NEXT_EPHEMERAL_ID для скачанных, но не импортированных треков), а furumi-tui уже использует для них ключ fed:{owner}:{item_id}. Поэтому вариант называется Federated, а не Pending(i64). Для элементов без строки библиотеки и без источника добавлен Transient(id), чтобы такой элемент никогда не считался строкой библиотеки.
  • Маркер −1 совпадает с id первого ожидающего федеративного трека. Это допустимо, потому что отрицательный id ничего не идентифицирует; TrackItem::key их различает (проверено тестом).
  • TrackItemKey не получил варианта с content id: ключ остаётся идентичностью источника, а сопоставление музыки по содержимому — забота клиента, у которого оно уже есть. Так ключ не меняет смысл при импорте трека.
  • Для приватной заглушки TrackItem не создаётся: у неё нет идентичности, а любой TrackItem с неотрицательным id стал бы строкой библиотеки. from_playback_track возвращает перечисление, а не Option, чтобы музыка и заглушка не смешивались.
  • Предварительный выпуск, чей id занят, удаляется, а не сливается с занявшим выпуском (source = 'feed'): у него нет персональных данных, а метаданные приходят из ленты.
  • TrackItem не реализует serde, поэтому атрибуты serde(default, skip_serializing_if) неприменимы. Чтобы не расширять API, serde не добавлялся.
  • Отметки операций передаются трейтом StampSource, а не одним готовым stamp. Отписка создаёт две операции, и отметка запрашивается только тогда, когда операция реально создаётся.
  • Локальный каталог (podcasts) берёт метаданные из победившего регистра подписки, пока устройство само не обновило ленту. Описание сохраняется через COALESCE, потому что в snapshot его нет. Каталог — локальные данные для показа, а не синхронизируемое состояние. Сходимость проверяется по синхронизируемому состоянию.

Совместимость и версии

  • Версии furumi-library 0.3.0 и music-dht 0.6.0 не менялись (подняты в F1).
  • TrackItem получил новое поле. Для клиентов, которые создают TrackItem литералом, это ломающее изменение в рамках 0.x (записано в CHANGELOG).
  • Новые публичные элементы: TrackItem::key, перечисление TrackItemKey, TrackItem::from_playback_track и перечисление PlaybackItem { Music, PodcastEpisode(Box<TrackItem>), Private } (оба перечисления реэкспортированы в корне крейта), константа TrackItem::NOT_A_LIBRARY_ROW. Ключи этот крейт нигде не сохраняет. podcast_track_id и PODCAST_TRACK_ID_MAX из промежуточного коммита e627be5 удалены в 06ac369 и в итоговом API отсутствуют.
  • furumi-library теперь включает feature podcast-feed у music-dht и использует tempfile в dev-зависимостях. В Cargo.lock добавилась одна строка.
  • Wire-форматы, ALPN и версия протокола не менялись: хранилище создаёт только полезные нагрузки операций F1. Схема podcasts.sqlite3 (v2) по итогам ревью не менялась.

Как проверено (macOS, rustc 1.100.0)

cargo fmt --all -- --check                                                   # OK
cargo check --workspace --all-targets --all-features                         # OK
cargo clippy --workspace --all-targets --all-features -- -D warnings \
  -A clippy::chunks_exact_to_as_chunks                                       # OK, без предупреждений
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features \
  -p music-dht -p furumi-library                                             # OK
cargo test --workspace                                                       # все тесты прошли
cargo test --workspace --all-features                                        # все тесты прошли

Вершина ветки d2530dc, CARGO_TARGET_DIR=/Users/krypton/furumi/gitea/.targets/frid-f2.

  • Clippy. Без -A единственная ошибка — уже существовавшая clippy::chunks_exact_to_as_chunks в furumi-library/src/lib.rs:3502 (на rustc 1.100). Её я не трогал. Cargo также выводит два старых предупреждения манифеста о неиспользуемых workspace-зависимостях clap и tracing-subscriber; корневой Cargo.toml не менялся.
  • Число тестов. federation-net 31 + 10, furumi-library 62, music-dht 182 + 2 + 3 + 1, doctests 1 + 1 + 5. С --all-features — те же числа.
  • Тесты в furumi-library. В модуле podcasts 27 тестов, 6 из них добавлены по итогам ревью. Ещё 6 тестов в models (3 из них — key_is_typed_by_source, episodes_share_the_sentinel_id_but_not_the_key и received_playback_tracks_never_copy_wire_ids) и 1 doctest. Используются только временные каталоги и in-memory базы. Тесты проверяют:
    • миграции:
      • из пустого файла;
      • из пустого прототипа;
      • из заполненного прототипа: база создана дословным SQL и процедурой прототипа, есть дубль URL, невалидный URL, невалидный аудио-URL, выпуск без GUID и последующая смена его идентификатора на GUID;
      • из v1, созданной самим хранилищем;
      • повторное открытие и 4 одновременных процесса;
      • отказ для новой версии и чужого файла с побайтной проверкой неизменности;
    • импорт выпуска без GUID, у которого сменился URL вложения: id совпадает с тем, что вычислит новое устройство. Сценарий из ревью с двумя устройствами: операция устройства A попадает на выпуск устройства B, прогресс B сохраняется;
    • перевод предварительного выпуска на id текущей ленты при первом обновлении, когда при импорте дубль не распознан; после этого id стабилен, а оставшаяся устаревшая строка того же элемента удаляется;
    • операция прогресса другого устройства до первого обновления: предварительная копия удаляется, остаётся одна строка с id ленты и позицией; то же для занятого GUID-идентификатора;
    • выпуск с прогрессом не переводится, позиция сохраняется;
    • параллельные записи служебного состояния: два соединения, 4 потока по 25 ошибок плюс set_cover_cache, ни одно обновление не теряется;
    • сходимость во всех перестановках:
      • 5 операций подписки, публикации и алиасов (120 порядков) и 6 операций прогресса и сеансов (720 порядков), с повторной доставкой;
      • результат совпадает с импортом snapshot и с порядком «snapshot, затем операции»;
    • устаревший snapshot и секции сверх лимита не портят более новое локальное состояние;
    • отписка сохраняет прогресс и историю, повторная подписка снова приватна;
    • обновление RSS со сменой названий, аудио-URL и выпусками без GUID сохраняет идентификаторы и прогресс;
    • выпуск, полученный через синхронизацию, сохраняет id после обновления ленты;
    • служебное состояние проверок, описания каталога и путь к обложке не попадают в JSON snapshot;
    • правила поколений: Superseded, AlreadyCompleted;
    • дедупликация сеансов, валидация и отклонение операций;
    • сезоны, фильтры, сортировка, поиск и постраничный вывод;
    • элемент подкаста: id, release_id и id исполнителя равны маркеру −1;
    • TrackItem::key для каждого вида: lib:123, fed:<owner>:<item_id> (не зависит от отрицательного счётчика), ep:ep1:…, tmp:-7; источник важнее числового id (выпуск с id = 42 остаётся выпуском, федеративный трек с id = −1 не совпадает с выпуском);
    • два разных выпуска имеют одинаковый id = −1, но разные ключи (и в HashSet, и в строковой форме); тот же выпуск даёт тот же ключ;
    • from_playback_track: wire-выпуск с id = 0/release_id = 0 и даже с подменёнными полями отображения становится выпуском с маркерами −1 и ключом ep:; приватная заглушка — Private; элемент без источника и с Music — Music.
  • Проверка регрессионных тестов. Три теста поведения первого ревью (импорт, перевод при обновлении, параллельные записи) запускались на коде до исправлений: все три падают. Тест параллельных записей проходит стабильно (8 из 8 повторных запусков). Тесты повторного ревью на прежнем refresh.rs: remote_progress_before_the_first_refresh_leaves_no_duplicate_episode и обновлённый first_refresh_rekeys_provisional_imported_guidless_episodes падают; remote_progress_on_the_guid_id_removes_the_imported_copy падает без удаления в rekey_legacy_guids.
  • cargo check --workspace --all-targets --all-features на каждом коммите стека от 35115ec до d2530dc: ок.

Ограничения

  • Проверено только на macOS. Linux и Windows не проверялись. С реальным клиентом хранилище проверено только в составе стека: TUI (MR-T2/T3) работает на PodcastStore в межклиентском прогоне (см. «Межклиентская проверка»). Веб использует собственное хранилище на PostgreSQL (MR-W2), а не этот модуль.
  • Если импортированный выпуск начали слушать на этом устройстве до первого обновления ленты, его id не меняется. Если он отличается от id текущей ленты, элемент ленты появится отдельным выпуском (персональные данные не удаляются и не переносятся). TUI должен обновлять ленты сразу после миграции: podcasts_due_for_refresh возвращает импортированные подкасты как готовые к проверке.
  • Предварительные выпуски, которых уже нет в ленте, остаются со старым id и in_feed = false. Персональных данных у них нет.
  • Маркер −1 — страховка для старого кода, а не идентичность. Откат track_key в furumi-tui на local:{id} (state.rs) без изменений склеит все выпуски в один. MR-T2 должен добавить в track_key ветку ep: (через TrackItem.podcast или TrackItem::key) перед откатом на id, сохранив сопоставление музыки по content id, преобразовывать полученные PlaybackTrack через TrackItem::from_playback_track вместо копирования release_id, и проверять is_podcast() в очереди, переходе к релизу и похожих треках.
  • Строковая форма fed:<owner>:<item_id> однозначна, пока owner — endpoint id узла, в котором нет :. Авторитетны Eq/Hash самого TrackItemKey.
  • Поколения больше i64::MAX не хранятся: такие записи отклоняются. Корректные клиенты их не создают.
  • Алиасы подкастов, у которых нет регистра подписки, не попадают в snapshot: в F1 нет такой секции.

Зависимости от других MR

Stacked MR поверх MR-F1 (ветка podcasts/contract). К этому MR относятся только восемь последних коммитов ветки podcasts/store (git log --oneline podcasts/contract..podcasts/store):

  • 35115ec Add TrackItem.podcast for podcast queue items
  • e22c470 Add SQLite podcast store with prototype import
  • 49ae642 Document the SQLite podcast store
  • e627be5 Give podcast queue items fail-safe negative ids
  • 9709f5e Re-key imported GUID-less episodes and make fetch-state writes atomic
  • 06ac369 Key podcast queue items by source, not by a negative id range
  • b8d8b53 Remove imported podcast episodes that duplicate a held id (повторное ревью)
  • d2530dc Convert received playback items without copying wire ids (повторное ревью)

Коммиты от 65d6ca2 включительно и ниже относятся к MR-F1. От этого MR зависят MR-F3 (ветка podcasts/discovery перенесена на d2530dc) и MR-T2 (TUI).

Ветка Sanapach/frid:podcasts/store → Furumi/frid:podcasts/contract, если эта ветка-основание есть в Furumi/frid. Иначе MR открывается в main: он зависит от MR-F1, и его diff включает семь коммитов MR-F1.

Cargo.lock и [patch]

  • В самом frid [patch] нет. Cargo.lock workspace-а этот MR меняет одной строкой (tempfile в dev-зависимостях furumi-library).
  • MR-T2 собирается против этой ветки через локальный .cargo/config.toml с [patch.crates-io] на путь рабочей копии. Файл исключён из git и в коммиты не попадает. Перед merge Cargo.lock клиента перегенерируется против запушенной ветки форка: git-зависимость https://gt.hexor.cy/Sanapach/frid.git, branch = "podcasts/store", последний коммит MR-T2 — «Point frid deps at the fork branch». После публикации music-dht 0.6.0 и furumi-library 0.3.0 lock перегенерируется против crates.io, а [patch] удаляется.

Межклиентская проверка

PodcastStore из этого MR — хранилище TUI в межклиентском прогоне всего стека (TUI 0.5.0 на frid podcasts/discovery @ 9c82f6d). Прошли все проверки TUI ↔ TUI (23 из 23) и TUI ↔ веб (37 pass, 0 fail). Среди них подписка без повторного ввода URL, отписка с сохранением прогресса, «Начать сначала» против позднего офлайн-checkpoint и перезапуск с сохранением всех подкастовых данных. Таблица сценариев — в MR-T2 и MR-T3. Отдельно на ветке podcasts/store межклиентских прогонов не было.

🤖 Generated with Claude Code

> **Серия «Подкасты»:** 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 и зависимости — в разделе зависимостей ниже. ## Что сделано Реализовано решение **Р3** для SQLite-клиентов: новый модуль `furumi_library::podcasts` с `PodcastStore`. Это эталонное хранилище контракта подкастов из `music_dht::podcast` (MR-F1). Его будет использовать TUI (MR-T2). - **Отдельный файл** `podcasts.sqlite3` (`PODCAST_DB_FILE`). Путь передаёт клиент. Включены WAL, внешние ключи и busy timeout 5 с. - **Миграции по `PRAGMA user_version`.** Каждая выполняется в отдельной транзакции `BEGIN IMMEDIATE` и заново читает версию, поэтому повторное открытие и одновременный запуск нескольких процессов безопасны. - v1 — схема прототипа из исходного PR, перенесена дословно. - v2 — новая модель. Таблицы прототипа переименовываются в `legacy_podcasts` / `legacy_podcast_episodes`, а не удаляются, и их данные импортируются. - Файл от более новой версии Furumi или чужой файл (например, по ошибке переданный `library.db`) отклоняется до любой записи, включая переключение в WAL. Файл остаётся побайтно неизменным. - **Импорт прототипа.** - Каждая лента становится подкастом. `podcast_id` вычисляется по каноническому URL функциями F1. - Для каждой ленты создаётся регистр подписки: подписан, поколение 0, `hlc` = `added_at`, `op_id` = `legacy-import:<id>`. Подписка приватная. - Невалидные URL и непригодные выпуски попадают в `legacy_quarantine`, исходные строки остаются в `legacy_*`. - Идентификаторы выпусков вычисляются по правилу идентичности F1. - Прототип хранил выпуск без GUID отдельной строкой на каждый URL вложения. Строки одного такого выпуска (та же секунда публикации, то же нормализованное название и та же ссылка или её отсутствие) схлопываются в самую новую. Остальные попадают в карантин как «duplicate episode». - Импортированные выпуски без GUID считаются **предварительными**. Первое обновление RSS, в котором они есть, переводит их на идентификатор, который даёт текущая лента (подробнее ниже). - ETag, Last-Modified, время проверки, ошибка и кэш обложки переносятся в локальное служебное состояние (`podcast_fetch_state`). - **Таблицы.** Подкасты (метаданные канала), алиасы лент, сезоны (вычисляются по выпускам), выпуски, регистры подписки, публикации и прогресса, сеансы прослушивания (G-set) и локальное служебное состояние проверок (`podcast_fetch_state`), которое никогда не попадает в синхронизацию. - **Локальные действия.** Каждое действие применяет операцию к хранилищу и возвращает её (`PodcastLocalOp`) для журнала синхронизации клиента: - `subscribe`, `unsubscribe` (прогресс и история сохраняются), `set_shared`; - `start_session`, `checkpoint` (поколение не меняется), `seek`, `restart`, `complete_session`, `mark_played`, `mark_unplayed` (поколение повышается через `explicit_generation`); - `record_listen_session`. Отметку операции (`op_id`, устройство, `hlc`) выдаёт журнал клиента через трейт `StampSource`. - **Синхронизация.** - `apply_remote_op` обрабатывает все пять видов `podcast_*`. - `fill_snapshot` / `export_snapshot` формируют секции snapshot с ограничением по F1 (`bound_podcast_state_to`). - `apply_snapshot` объединяет полученные секции. - Локальные действия, принятые операции и snapshot проходят **один путь кода**: материализаторы `SyncOpWire::podcast_*` и функции слияния F1. - **Обновление RSS (`apply_feed`).** - Обновляет метаданные канала и выпусков, включая URL аудио. Идентификаторы выпусков сохраняются по правилу F1, с учётом выпусков, полученных через синхронизацию. - Предварительные импортированные выпуски без прогресса и сеансов переводятся на идентификатор текущей ленты. Перевод делается в две фазы. Сопоставление идёт по вложению, затем по ссылке, затем по дате и названию; GUID при этом не учитывается. Персональные данные при этом не переносятся, потому что их у таких выпусков нет. - Если этот идентификатор уже занят выпуском, который остаётся (например, строкой, созданной удалённой операцией до первого обновления), предварительный выпуск — дубль элемента ленты, и он удаляется. То же, когда `legacy_guid` оказывается настоящим GUID элемента, а GUID-идентификатор уже занят. - Выпуски, пропавшие из ленты, сохраняются. - Постоянный редирект и `itunes:new-feed-url` превращаются в алиасы. Операция `podcast_feed_aliases_added` создаётся только если набор алиасов изменился. - Подписку, публикацию, прогресс и сеансы обновление **не трогает**. - **Служебное состояние проверок.** Все записи (`record_fetch_*`, `set_cover_cache`) читают и пишут строку под одной блокировкой в одной транзакции `BEGIN IMMEDIATE`. Параллельные записи из нескольких потоков или процессов не теряют ни столбцы, ни приращения счётчика ошибок. - **Запросы для UI.** Список подкастов (подписанные или все, со счётчиками непрослушанных), сезоны, выпуски (фильтр по сезону и статусу, поиск по тексту с Unicode-нормализацией, сортировка по дате или номеру, постраничный вывод), позиция продолжения, `episode_ref` / `episode_track` для очереди, история прослушиваний, служебное состояние проверок для планировщика (`podcasts_due_for_refresh`). - **`TrackItem.podcast: Option<PodcastEpisodeRef>`.** Добавлены `TrackItem::podcast_episode`, `is_podcast`, `podcast_episode_ref`. - Идентичность выпуска в очереди задаёт **только** явный источник `TrackItem.podcast` (`EpisodeId`). Никакого зарезервированного диапазона отрицательных id нет (требования §4, §10.2). - `id`, `release_id` и id исполнителя у всех выпусков равны фиксированному маркеру `TrackItem::NOT_A_LIBRARY_ROW` = −1. Это то же соглашение «не строка библиотеки», что у ожидающих федеративных треков. Маркер не несёт идентичности, общий для всех выпусков и не декодируется. Он лишь не даёт старому музыкальному коду (`id >= 0`, `release_id < 0`) принять выпуск за трек, релиз или исполнителя библиотеки с id 0. - **`TrackItem::key() -> TrackItemKey`** — типизированная идентичность источника элемента (Hash/Eq/Ord, `Display` со стабильной строкой): - `Library(id)` → `lib:123` — строка библиотеки (`id >= 0`); - `Federated { owner, item_id }` → `fed:<owner>:<item_id>` — федеративный трек не из библиотеки; его отрицательный id — счётчик процесса и в ключ не входит (та же форма, что `fed:` в `track_key` furumi-tui); - `PodcastEpisode(EpisodeId)` → `ep:<episode id>`, например `ep:ep1:…`; - `Transient(id)` → `tmp:-5` — элемент без библиотечной строки и без явного источника; furumi-library такие не создаёт. Приоритет: `podcast` → неотрицательный `id` → `fed` → `Transient`. - В rustdoc, README, `ARCHITECTURE.md` и `PODCASTS.md` записано: выпуск идентифицируется только `TrackItem.podcast` / `ep:` (в протоколе — `PlaybackSource`) и никогда не ключуется по `id`; ключ вида `local:{id}` склеил бы все выпуски в один. У `TrackItemKey` нет эквивалентности по content id: ожидающий федеративный трек (`fed:`) и его импортированная копия (`lib:`) различаются. Поэтому клиенты, которые сопоставляют музыку сначала по content id (как `track_key` в furumi-tui), так и делают дальше и добавляют ветку для подкастов перед любым откатом на `id`. - **`TrackItem::from_playback_track(&PlaybackTrack) -> PlaybackItem`** — преобразование полученного элемента воспроизведения без копирования wire-id. В F1 у выпуска и у приватной заглушки Jam `id` и `release_id` равны 0. `PlaybackItem::PodcastEpisode(Box<TrackItem>)` строится через `TrackItem::podcast_episode` (маркеры −1, ключ `ep:`) независимо от устаревших полей отображения; `PlaybackItem::Private` — неиграемая заглушка без `TrackItem` и без идентичности; `PlaybackItem::Music` оставляет музыку клиентскому пути (content id, затем `fed`). - В rustdoc `TrackItem::podcast_episode` перечислены отличия от wire-формы F1: id −1 вместо 0, `release_year` — год публикации (на проводе `None`), `audio_format` — `None` (MIME остаётся в ссылке). - Запросы библиотеки по-прежнему возвращают только музыку, схема `library.db` не изменилась. Музыкальный код обязан проверять `is_podcast`. - **Документация.** README крейта, `ARCHITECTURE.md`, новый раздел «SQLite reference store» в `PODCASTS.md` (схема и инварианты), `CHANGELOG.md`. ## Исправления по ревью 1. **Идентификаторы импортированных выпусков без GUID** (средняя важность, подтверждено). - **Проблема.** Если у такого выпуска менялся URL вложения, устаревшие строки прототипа делали ссылку и пару «дата + название» неуникальными. Тогда выпуск получал id, которого новое устройство никогда не вычислит. После синхронизации прогресс нового устройства оказывался на скрытом выпуске. - **Исправление.** Схлопывание дублей при импорте и перевод предварительных выпусков на идентификатор текущей ленты при первом обновлении (см. выше). 2. **`TrackItem::podcast_episode` с `id 0`** (средняя важность, подтверждено по коду furumi-tui: `apply_queue_refresh`, `track_key`, `release_id < 0`). - **Проблема.** Клиенты считали каждый выпуск треком библиотеки с id 0: удаляли его из очереди при обновлении библиотеки, а ключи всех выпусков совпадали (`local:0`). - **Первое исправление (`e627be5`).** Отрицательный id для каждого выпуска из зарезервированного диапазона ниже `PODCAST_TRACK_ID_MAX`, вычисляемый из дайджеста `EpisodeId`. - **Замена (`06ac369`).** Это и есть «магический диапазон отрицательных id», который требования (§4, §10.2) запрещают в общем контракте, а furumi-library — общий код FRID. `TrackItem::podcast_track_id` и `PODCAST_TRACK_ID_MAX` удалены. Выпуски получают фиксированный маркер −1 (`id`, `release_id`, id исполнителя), а идентичность — только из `TrackItem.podcast` через `TrackItem::key()` / `TrackItemKey`. Старые проверки `id < 0` / `release_id < 0` по-прежнему пропускают выпуски; код, который откатывается на `id` как ключ (`track_key` в furumi-tui, `local:{id}`), должен проверять выпуск (`ep:`) до этого отката (рекомендация уточнена в п. 5). 3. **Гонка в `update_fetch_state`** (низкая важность, подтверждено). - **Проблема.** Чтение и запись шли под двумя разными захватами мьютекса, поэтому параллельные вызовы могли затереть друг друга. - **Исправление.** Одна блокировка и одна транзакция. ### Повторное ревью 4. **Заблокированный перевод оставлял вечный дубль выпуска** (средняя важность, подтверждено; коммит `b8d8b53`). - **Проблема.** Устройство A мигрирует базу прототипа и до первого обновления RSS применяет операцию прогресса нового устройства B. Появляется строка `source = 'sync'` с id текущей ленты. При обновлении предварительный выпуск сопоставлялся с тем же элементом, но его перевод блокировался, и он навсегда оставался второй копией с `in_feed = 0`, видимой в `episodes()` и счётчиках. Это нарушало требование §4: выпуски не должны дублироваться. - **Исправление.** Если цель занята выпуском, который остаётся, предварительный выпуск удаляется: прогресса и сеансов у него нет, а его метаданные всё равно перезаписал бы элемент ленты. Удалённый дубль освобождает свой id для других переводов. То же в `rekey_legacy_guids`, когда GUID-идентификатор уже занят. Удаление дополнительно защищено условием «`legacy_guid` задан, нет прогресса и сеансов». Сезоны пересчитываются, как и раньше, в конце `apply_feed`. - **Тесты.** `remote_progress_before_the_first_refresh_leaves_no_duplicate_episode` (точный порядок из ревью: операция B до первого обновления A; после каждого из двух обновлений одна строка «Pilot» с id ленты и позицией B), `remote_progress_on_the_guid_id_removes_the_imported_copy` (путь через `legacy_guid`). Ожидание в `first_refresh_rekeys_provisional_imported_guidless_episodes` уточнено: устаревшая строка того же элемента, которую при первом обновлении нельзя было сопоставить, удаляется вторым, когда остаётся единственным предварительным выпуском и её ссылка указывает на этот элемент. Все три теста падают на прежнем коде. 5. **Слишком широкая рекомендация про `TrackItem::key`** (низкая важность, подтверждено по furumi-tui `state.rs:2179-2186`, `app/mod.rs:3068-3117`, только чтение; коммит `d2530dc`). - **Проблема.** Документация требовала сопоставлять всё по `TrackItem::key`. Но у ключа нет эквивалентности по content id, а обновление очереди в TUI заменяет ожидающий `fed`-элемент его библиотечной копией именно по content id. Буквальное следование сломало бы эту замену. - **Исправление.** Рекомендация сужена (см. выше): ключ — идентичность источника; выпуск никогда не ключуется по `id`; музыкальное сопоставление по content id остаётся, в него добавляется ветка подкастов перед откатом на `id`. Rustdoc, README, `ARCHITECTURE.md`, `PODCASTS.md` и `CHANGELOG.md` обновлены. 6. **Wire-id 0 у выпусков и приватных заглушек** (низкая важность, подтверждено; коммит `d2530dc`). - **Проблема.** Маркер −1 защищал только элементы, созданные через `TrackItem::podcast_episode`. F1 передаёт выпуск и приватную заглушку с `id = 0` и `release_id = 0`; клиент, копирующий поля (как `to_track_item` в furumi-tui), получил бы «релиз 0», а все заглушки совпали бы по `lib:0`. - **Исправление.** `TrackItem::from_playback_track` / `PlaybackItem` (см. выше) и документация: wire-id подкастов и заглушек равны 0 и не копируются. Формулировка «display fields mirror» исправлена. Тест `received_playback_tracks_never_copy_wire_ids`. ## Решения и отступления от плана - В контракте F1 **пять** видов операций, а не четыре: добавилась `podcast_feed_aliases_added`. Обрабатываются все пять. - В схеме прототипа **нет данных о прослушивании и позиции**: позиция жила только в памяти (проверены `store.rs`, `mod.rs`, `app/podcast_runtime.rs`). Поэтому импорт не создаёт регистров прогресса, и параметр с id устройства не нужен. Импортированные подписки доходят до других устройств через snapshot. - Прототип записывал URL вложения в `guid`, когда у выпуска не было GUID. Такие строки импортируются как выпуски без GUID и считаются предварительными до первого обновления RSS. Исходное значение хранится в `episodes.legacy_guid`. Если обновление покажет это значение как настоящий GUID, выпуск получает GUID-идентификатор. Если выпуск сопоставлен с элементом ленты по вложению, ссылке или дате и названию, он получает идентификатор этого элемента. И то и другое — только при отсутствии у выпуска прогресса и сеансов. - Дубли при импорте схлопываются, только если совпадают и секунда публикации, и нормализованное название, и ссылка. Одной общей ссылки (например, домашней страницы шоу) недостаточно, чтобы не склеить разные выпуски. Остальные случаи исправляет первое обновление RSS. - Для пустого файла миграция тоже идёт через v1 (по плану: миграция 1 — схема PR). Поэтому таблицы `legacy_*` существуют и пустые. - У ожидающих федеративных треков ключ — `(owner, item_id)` из `TrackItem.fed`, а не отрицательный id: id у них — счётчик процесса (в furumi-tui ещё и `NEXT_EPHEMERAL_ID` для скачанных, но не импортированных треков), а furumi-tui уже использует для них ключ `fed:{owner}:{item_id}`. Поэтому вариант называется `Federated`, а не `Pending(i64)`. Для элементов без строки библиотеки и без источника добавлен `Transient(id)`, чтобы такой элемент никогда не считался строкой библиотеки. - Маркер −1 совпадает с id первого ожидающего федеративного трека. Это допустимо, потому что отрицательный id ничего не идентифицирует; `TrackItem::key` их различает (проверено тестом). - `TrackItemKey` не получил варианта с content id: ключ остаётся идентичностью источника, а сопоставление музыки по содержимому — забота клиента, у которого оно уже есть. Так ключ не меняет смысл при импорте трека. - Для приватной заглушки `TrackItem` не создаётся: у неё нет идентичности, а любой `TrackItem` с неотрицательным id стал бы строкой библиотеки. `from_playback_track` возвращает перечисление, а не `Option`, чтобы музыка и заглушка не смешивались. - Предварительный выпуск, чей id занят, удаляется, а не сливается с занявшим выпуском (`source = 'feed'`): у него нет персональных данных, а метаданные приходят из ленты. - `TrackItem` не реализует serde, поэтому атрибуты `serde(default, skip_serializing_if)` неприменимы. Чтобы не расширять API, serde не добавлялся. - Отметки операций передаются трейтом `StampSource`, а не одним готовым stamp. Отписка создаёт две операции, и отметка запрашивается только тогда, когда операция реально создаётся. - Локальный каталог (`podcasts`) берёт метаданные из победившего регистра подписки, пока устройство само не обновило ленту. Описание сохраняется через COALESCE, потому что в snapshot его нет. Каталог — локальные данные для показа, а не синхронизируемое состояние. Сходимость проверяется по синхронизируемому состоянию. ## Совместимость и версии - Версии `furumi-library 0.3.0` и `music-dht 0.6.0` не менялись (подняты в F1). - `TrackItem` получил новое поле. Для клиентов, которые создают `TrackItem` литералом, это ломающее изменение в рамках 0.x (записано в CHANGELOG). - Новые публичные элементы: `TrackItem::key`, перечисление `TrackItemKey`, `TrackItem::from_playback_track` и перечисление `PlaybackItem { Music, PodcastEpisode(Box<TrackItem>), Private }` (оба перечисления реэкспортированы в корне крейта), константа `TrackItem::NOT_A_LIBRARY_ROW`. Ключи этот крейт нигде не сохраняет. `podcast_track_id` и `PODCAST_TRACK_ID_MAX` из промежуточного коммита `e627be5` удалены в `06ac369` и в итоговом API отсутствуют. - `furumi-library` теперь включает feature `podcast-feed` у `music-dht` и использует `tempfile` в dev-зависимостях. В `Cargo.lock` добавилась одна строка. - Wire-форматы, ALPN и версия протокола не менялись: хранилище создаёт только полезные нагрузки операций F1. Схема `podcasts.sqlite3` (v2) по итогам ревью не менялась. ## Как проверено (macOS, rustc 1.100.0) ``` cargo fmt --all -- --check # OK cargo check --workspace --all-targets --all-features # OK cargo clippy --workspace --all-targets --all-features -- -D warnings \ -A clippy::chunks_exact_to_as_chunks # OK, без предупреждений RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features \ -p music-dht -p furumi-library # OK cargo test --workspace # все тесты прошли cargo test --workspace --all-features # все тесты прошли ``` Вершина ветки `d2530dc`, `CARGO_TARGET_DIR=/Users/krypton/furumi/gitea/.targets/frid-f2`. - **Clippy.** Без `-A` единственная ошибка — уже существовавшая `clippy::chunks_exact_to_as_chunks` в `furumi-library/src/lib.rs:3502` (на rustc 1.100). Её я не трогал. Cargo также выводит два старых предупреждения манифеста о неиспользуемых workspace-зависимостях `clap` и `tracing-subscriber`; корневой `Cargo.toml` не менялся. - **Число тестов.** federation-net 31 + 10, furumi-library 62, music-dht 182 + 2 + 3 + 1, doctests 1 + 1 + 5. С `--all-features` — те же числа. - **Тесты в furumi-library.** В модуле `podcasts` 27 тестов, 6 из них добавлены по итогам ревью. Ещё 6 тестов в `models` (3 из них — `key_is_typed_by_source`, `episodes_share_the_sentinel_id_but_not_the_key` и `received_playback_tracks_never_copy_wire_ids`) и 1 doctest. Используются только временные каталоги и in-memory базы. Тесты проверяют: - миграции: - из пустого файла; - из пустого прототипа; - из заполненного прототипа: база создана дословным SQL и процедурой прототипа, есть дубль URL, невалидный URL, невалидный аудио-URL, выпуск без GUID и последующая смена его идентификатора на GUID; - из v1, созданной самим хранилищем; - повторное открытие и 4 одновременных процесса; - отказ для новой версии и чужого файла с побайтной проверкой неизменности; - импорт выпуска без GUID, у которого сменился URL вложения: id совпадает с тем, что вычислит новое устройство. Сценарий из ревью с двумя устройствами: операция устройства A попадает на выпуск устройства B, прогресс B сохраняется; - перевод предварительного выпуска на id текущей ленты при первом обновлении, когда при импорте дубль не распознан; после этого id стабилен, а оставшаяся устаревшая строка того же элемента удаляется; - операция прогресса другого устройства до первого обновления: предварительная копия удаляется, остаётся одна строка с id ленты и позицией; то же для занятого GUID-идентификатора; - выпуск с прогрессом не переводится, позиция сохраняется; - параллельные записи служебного состояния: два соединения, 4 потока по 25 ошибок плюс `set_cover_cache`, ни одно обновление не теряется; - сходимость во всех перестановках: - 5 операций подписки, публикации и алиасов (120 порядков) и 6 операций прогресса и сеансов (720 порядков), с повторной доставкой; - результат совпадает с импортом snapshot и с порядком «snapshot, затем операции»; - устаревший snapshot и секции сверх лимита не портят более новое локальное состояние; - отписка сохраняет прогресс и историю, повторная подписка снова приватна; - обновление RSS со сменой названий, аудио-URL и выпусками без GUID сохраняет идентификаторы и прогресс; - выпуск, полученный через синхронизацию, сохраняет id после обновления ленты; - служебное состояние проверок, описания каталога и путь к обложке не попадают в JSON snapshot; - правила поколений: `Superseded`, `AlreadyCompleted`; - дедупликация сеансов, валидация и отклонение операций; - сезоны, фильтры, сортировка, поиск и постраничный вывод; - элемент подкаста: `id`, `release_id` и id исполнителя равны маркеру −1; - `TrackItem::key` для каждого вида: `lib:123`, `fed:<owner>:<item_id>` (не зависит от отрицательного счётчика), `ep:ep1:…`, `tmp:-7`; источник важнее числового id (выпуск с `id = 42` остаётся выпуском, федеративный трек с `id = −1` не совпадает с выпуском); - два разных выпуска имеют одинаковый `id = −1`, но разные ключи (и в `HashSet`, и в строковой форме); тот же выпуск даёт тот же ключ; - `from_playback_track`: wire-выпуск с `id = 0`/`release_id = 0` и даже с подменёнными полями отображения становится выпуском с маркерами −1 и ключом `ep:`; приватная заглушка — `Private`; элемент без источника и с `Music` — `Music`. - **Проверка регрессионных тестов.** Три теста поведения первого ревью (импорт, перевод при обновлении, параллельные записи) запускались на коде до исправлений: все три падают. Тест параллельных записей проходит стабильно (8 из 8 повторных запусков). Тесты повторного ревью на прежнем `refresh.rs`: `remote_progress_before_the_first_refresh_leaves_no_duplicate_episode` и обновлённый `first_refresh_rekeys_provisional_imported_guidless_episodes` падают; `remote_progress_on_the_guid_id_removes_the_imported_copy` падает без удаления в `rekey_legacy_guids`. - `cargo check --workspace --all-targets --all-features` на каждом коммите стека от `35115ec` до `d2530dc`: ок. ## Ограничения - Проверено только на macOS. Linux и Windows не проверялись. С реальным клиентом хранилище проверено только в составе стека: TUI (MR-T2/T3) работает на `PodcastStore` в межклиентском прогоне (см. «Межклиентская проверка»). Веб использует собственное хранилище на PostgreSQL (MR-W2), а не этот модуль. - Если импортированный выпуск начали слушать **на этом устройстве** до первого обновления ленты, его id не меняется. Если он отличается от id текущей ленты, элемент ленты появится отдельным выпуском (персональные данные не удаляются и не переносятся). TUI должен обновлять ленты сразу после миграции: `podcasts_due_for_refresh` возвращает импортированные подкасты как готовые к проверке. - Предварительные выпуски, которых уже нет в ленте, остаются со старым id и `in_feed = false`. Персональных данных у них нет. - Маркер −1 — страховка для старого кода, а не идентичность. Откат `track_key` в furumi-tui на `local:{id}` (`state.rs`) без изменений склеит все выпуски в один. MR-T2 должен добавить в `track_key` ветку `ep:` (через `TrackItem.podcast` или `TrackItem::key`) **перед** откатом на `id`, сохранив сопоставление музыки по content id, преобразовывать полученные `PlaybackTrack` через `TrackItem::from_playback_track` вместо копирования `release_id`, и проверять `is_podcast()` в очереди, переходе к релизу и похожих треках. - Строковая форма `fed:<owner>:<item_id>` однозначна, пока `owner` — endpoint id узла, в котором нет `:`. Авторитетны `Eq`/`Hash` самого `TrackItemKey`. - Поколения больше `i64::MAX` не хранятся: такие записи отклоняются. Корректные клиенты их не создают. - Алиасы подкастов, у которых нет регистра подписки, не попадают в snapshot: в F1 нет такой секции. ## Зависимости от других MR Stacked MR поверх **MR-F1** (ветка `podcasts/contract`). К этому MR относятся только восемь последних коммитов ветки `podcasts/store` (`git log --oneline podcasts/contract..podcasts/store`): - `35115ec` Add TrackItem.podcast for podcast queue items - `e22c470` Add SQLite podcast store with prototype import - `49ae642` Document the SQLite podcast store - `e627be5` Give podcast queue items fail-safe negative ids - `9709f5e` Re-key imported GUID-less episodes and make fetch-state writes atomic - `06ac369` Key podcast queue items by source, not by a negative id range - `b8d8b53` Remove imported podcast episodes that duplicate a held id (повторное ревью) - `d2530dc` Convert received playback items without copying wire ids (повторное ревью) Коммиты от `65d6ca2` включительно и ниже относятся к MR-F1. От этого MR зависят MR-F3 (ветка `podcasts/discovery` перенесена на `d2530dc`) и MR-T2 (TUI). Ветка `Sanapach/frid:podcasts/store` → `Furumi/frid:podcasts/contract`, если эта ветка-основание есть в Furumi/frid. Иначе MR открывается в `main`: он зависит от MR-F1, и его diff включает семь коммитов MR-F1. ## `Cargo.lock` и `[patch]` - В самом frid `[patch]` нет. `Cargo.lock` workspace-а этот MR меняет одной строкой (`tempfile` в dev-зависимостях furumi-library). - MR-T2 собирается против этой ветки через локальный `.cargo/config.toml` с `[patch.crates-io]` на путь рабочей копии. Файл исключён из git и в коммиты не попадает. Перед merge `Cargo.lock` клиента перегенерируется против запушенной ветки форка: git-зависимость `https://gt.hexor.cy/Sanapach/frid.git`, `branch = "podcasts/store"`, последний коммит MR-T2 — «Point frid deps at the fork branch». После публикации `music-dht 0.6.0` и `furumi-library 0.3.0` lock перегенерируется против crates.io, а `[patch]` удаляется. ## Межклиентская проверка `PodcastStore` из этого MR — хранилище TUI в межклиентском прогоне всего стека (TUI 0.5.0 на frid `podcasts/discovery` @ `9c82f6d`). Прошли все проверки TUI ↔ TUI (23 из 23) и TUI ↔ веб (37 pass, 0 fail). Среди них подписка без повторного ввода URL, отписка с сохранением прогресса, «Начать сначала» против позднего офлайн-checkpoint и перезапуск с сохранением всех подкастовых данных. Таблица сценариев — в MR-T2 и MR-T3. Отдельно на ветке `podcasts/store` межклиентских прогонов не было. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
sanapach added 15 commits 2026-11-20 13:22:24 +00:00
Introduce music_dht::podcast, a pure module (no SQLite, HTTP or clock)
that every Furumi client uses for podcast identity and personal state:

- FeedUrl canonicalization that keeps the path and every query
  parameter byte-for-byte, PodcastId/EpisodeId derivation with
  domain-separated BLAKE3, feed aliases and the documented no-GUID
  episode identity rule;
- bounded PodcastMeta, EpisodeMeta and the self-contained
  PodcastEpisodeRef queue item;
- convergent merge rules for subscriptions (LWW, unsubscribe is state),
  share decisions (false is a tombstone), progress registers ordered by
  a Lamport generation, and listening sessions (G-set, one completion
  per session).

Tests cover every delivery permutation of small operation sets, late
checkpoints of old sessions, concurrent offline sessions and RSS
metadata updates that must not touch progress.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Port the tolerant RSS 2.0 / RSS 1.0 / Atom parser of the original
furumi-tui podcast work into music_dht::podcast::feed behind the
optional podcast-feed feature (quick-xml, encoding_rs, url). Episode
identity depends on what the parser extracts, so it must be shared by
all clients.

The port keeps its robustness (BOM and declared encodings, entities,
mismatched tags, depth and size limits, lenient dates, http(s)-only
media) and adds itunes:season, itunes:episode, itunes:episodeType,
guid isPermaLink and itunes:new-feed-url. Missing GUIDs stay absent
instead of falling back to the enclosure URL, and parsed items produce
identity hints and contract metadata.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Bump DEVICE_SYNC_PROTOCOL_VERSION to 4 (ALPN unchanged) and carry the
podcast contract between trusted devices:

- podcast_subscription_set, podcast_share_set, podcast_progress_set and
  podcast_listen_recorded operations with record materializers and
  validation; unsubscribe is LWW state, share=false is a tombstone;
- bounded podcast sections in SyncSnapshot, the recovery path for peers
  that upgrade after operations were hidden from them;
- PlaybackTrack.source with PlaybackSource::{Music, PodcastEpisode,
  Private}, reserved PlaybackStateWire.playback_rate and an optional
  self-reported protocol_version in DeviceProfileSet;
- gating helpers for peers below v4 (op_allowed_for_peer,
  playback_allowed_for_peer, playback_command_allowed_from_peer,
  SyncSnapshot::for_peer) and Jam privacy (redact_for_jam,
  redact_jam_snapshot, jam_command_allowed, restore_jam_private_items).

Tests show that a v3-shaped enum rejects a whole batch containing a new
kind, which is why gating is mandatory, and that legacy JSON still
parses and music-only messages keep their v3 shape.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add PODCASTS.md as the normative podcast contract: identity and URL
canonicalization, the no-GUID rule, synced versus local versus public
data, operation kinds and merge rules with examples, snapshot recovery,
version gating for peers below v4, Jam privacy and the reserved
playback_rate. Update PLAYBACK_PROTOCOL.md, ARCHITECTURE.md, the crate
READMEs and CHANGELOG.md.

Bump music-dht to 0.6.0 and furumi-library to 0.3.0: new public enum
variants and struct fields are breaking changes for 0.x, and
furumi-library re-exposes music-dht types.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Run the no-GUID matching stages across the whole document so a weak
date+title match of an earlier item cannot take a known episode that a
later item matches by enclosure. Keep feed links verbatim (trimmed only)
because they are identity material, and stop html_to_text from scanning
to the end of the text at every '<' when no '>' follows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Order subscription and share registers by a per-podcast Lamport
  generation before hlc_ms (next_podcast_generation), so clock skew
  cannot undo an observed unsubscribe or share decision.
- share=false is register state, not a compactable tombstone.
- Add podcast_feed_aliases_added so refreshes can sync aliases without
  touching the registers; SubscriptionRecord::feed_urls keeps the current
  feed URL resolvable beyond the alias bound.
- Carry progress_generation on queue items for handoff.
- Distinguish self-reported and relayed peer versions, and gate
  PairRequest by an optional inviter version in InviteWire.
- Give each podcast snapshot section its own byte budget, drop channel
  descriptions from snapshots and allow a caller-provided budget.
- Reject one-slash http(s) typos in FeedUrl::from_user_input.
- Pin that malformed ids and feed URLs reject the whole message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
TrackItem gains `podcast: Option<PodcastEpisodeRef>` with
`TrackItem::podcast_episode`, `is_podcast` and `podcast_episode_ref`.
Library queries keep returning music only (`podcast: None`); the library
database is unchanged. Music-only code paths must check `is_podcast`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New `furumi_library::podcasts::PodcastStore` in its own podcasts.sqlite3:

- user_version migrations in immediate transactions; version 1 is the
  prototype schema of the original podcast PR, version 2 renames its tables
  to legacy_* and imports feeds, episodes and fetch state with contract
  ids; unimportable rows go to legacy_quarantine; newer or foreign files
  are refused before anything is written;
- catalog (podcasts, feed aliases, seasons, episodes), subscription, share
  and progress registers, listening sessions and local-only fetch state;
- local actions that apply and return podcast sync operations, remote
  operation and snapshot application through the music-dht materializers
  and merge functions, bounded snapshot export;
- RSS refresh ingestion with stable episode ids and alias learning that
  never touches personal state, and queries for the UI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PODCASTS.md gains the "SQLite reference store" section (migrations,
prototype import, tables, invariants); ARCHITECTURE.md, the
furumi-library README and the changelog describe PodcastStore and
TrackItem.podcast.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
TrackItem::podcast_episode used id 0, release_id 0 and artist id 0, which
clients treat as library rows. Podcast items now get a negative id derived
from the episode id (TrackItem::podcast_track_id, at most
PODCAST_TRACK_ID_MAX, below pending federated ids) and release/artist id -1,
so existing id < 0 / release_id < 0 checks skip them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The prototype kept one row per enclosure URL for GUID-less items, so stale
rows could change which identity key is unique and give imported episodes
ids a fresh device never derives. The import now collapses rows of one item
seen under several enclosure URLs, and the first refresh re-keys imported
GUID-less episodes without progress or sessions to the ids the current feed
gives.

Fetch-state writes read and write the row under one lock and one immediate
transaction, so concurrent writers no longer lose columns or failure counts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The per-episode negative ids (TrackItem::podcast_track_id below
PODCAST_TRACK_ID_MAX) were a magic id range in shared code, which the
podcast requirements forbid. Podcast items now use the fixed sentinel
TrackItem::NOT_A_LIBRARY_ROW (-1) as id, release_id and artist id; it
carries no identity. Their identity is TrackItem.podcast alone.

Add TrackItem::key returning a typed TrackItemKey (library row, federated
owner and item id, podcast episode id, or transient), with the stable
string forms lib:<id>, fed:<owner>:<item_id>, ep:<episode id> and
tmp:<id>, so clients key queue items by source instead of by numeric id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A provisional imported GUID-less episode whose feed item id is already
held by an episode that stays (typically one a remote operation created
before this device's first refresh) is now deleted instead of kept as a
second, never re-keyed copy. The same applies when its legacy GUID turns
out to be the item's real GUID. Such episodes carry no personal state.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Convert received playback items without copying wire ids
CI / check (pull_request) Successful in 2m18s
d2530dca6c
Add TrackItem::from_playback_track and PlaybackItem: a received podcast
episode becomes TrackItem::podcast_episode (sentinel ids) and a Jam
private placeholder gets no TrackItem, so the wire ids (0 for both) are
never copied. Narrow the TrackItem::key guidance: it is the source
identity, episodes must never be keyed by id, and content-first music
matching stays as it is. Document how TrackItem::podcast_episode differs
from the wire form.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
sanapach changed title from Podcasts/store to Подкасты в FRID: SQLite-хранилище PodcastStore, импорт прототипа и TrackItem.podcast (MR-F2) 2026-11-20 13:33:45 +00:00
ab merged commit 3046c3f924 into main 2026-11-20 13:51:51 +00:00
Sign in to join this conversation.
No Reviewers
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Furumi/frid#2