Подкасты в FRID: общий контракт music_dht::podcast, RSS-парсер и device-sync v4 (MR-F1) #1

Merged
ab merged 7 commits from sanapach/frid:podcasts/contract into main 2026-11-20 13:51:49 +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 и зависимости — в разделе зависимостей ниже.

Что сделано

Первый MR серии «Подкасты» (MR-F1 из PODCASTS_PLAN.md). В FRID добавлен общий контракт подкастов. На него опираются все следующие MR: F2, T2, W1, W2, F3.

music_dht::podcast — чистый модуль без SQLite, HTTP и часов

  • Идентичность.
    • FeedUrl — каноничный URL ленты.
      • Схема и хост приводятся к нижнему регистру.
      • Порт по умолчанию и фрагмент убираются.
      • Путь и вся строка запроса сохраняются байт в байт.
      • Отклоняются не-http(s), userinfo, пробелы, \ и не-ASCII хост (нужна форма xn--).
    • FeedUrl::from_user_input разбирает пользовательский ввод: feed:, podcast:, pcast:, itpc: и URL без схемы. Опечатки вида https:/host отклоняются.
    • PodcastId = "pod1:" + base32(BLAKE3("furumi-podcast:podcast:v1\0" + url)). ID вычисляется по URL первой подписки.
    • EpisodeId = "ep1:" + base32(BLAKE3("furumi-podcast:episode:v1\0" + podcast_id + key)). Ключи: guid:, link:, date-title:, enclosure:.
  • Правило без GUID (resolve_episode_ids, нормативное).
    • Выпуск с GUID получает ID по GUID.
    • Выпуски без GUID сопоставляются с уже известными в три этапа по всему документу: по enclosure, затем по <link>, затем по паре (дата, нормализованное название). Каждый этап отрабатывает для всех выпусков, прежде чем начнётся следующий, поэтому результат не зависит от порядка элементов в ленте.
    • Если совпадения нет, новый ID строится по первому доступному ключу: link → дата+название → enclosure.
    • Ссылки, которые повторяются в ленте или совпадают со ссылкой канала, выпуск не идентифицируют.
  • Алиасы ленты.
    • merge_feed_aliases — ограниченное grow-only множество: исходный URL плюс 8 лексикографически наименьших.
    • SubscriptionRecord::feed_urls() — алиасы плюс текущий podcast.feed_url. Он участвует в resolve_podcast_id, даже если не поместился в ограничение множества.
  • DTO.
    • PodcastMeta, EpisodeMeta: сезон, номер, episodeType, длительность и дата в мс, URL аудио, MIME, размер, обложка, ссылка.
    • PodcastEpisodeRef — самодостаточный и ограниченный элемент очереди. Необязательное поле progress_generation — подсказка для переноса воспроизведения.
    • Валидация границ: заголовок до 1000 символов, описание до 4000, URL до 2048 байт.
  • Правила слияния. Все функции коммутативны, ассоциативны и идемпотентны. Ничьи разрешаются полным порядком.
    • SubscriptionRecord и ShareRecord — LWW по (generation, hlc_ms, op_id).
      • generation — счётчик Лэмпорта для подкаста, один на оба регистра: next_podcast_generation = max + 1.
      • Действие, совершённое после того, как устройство увидело чужую запись, побеждает её при любых часах.
      • Отписка и shared = false — состояние, а не tombstone. Они никогда не уплотняются.
      • Прогресс и история при отписке сохраняются.
    • effective_share: публикация действует, только если решение «Поделиться» упорядочено после последней записи подписки.
    • ProgressRecord — регистр с порядком (generation, hlc_ms, device_id, op_id).
      • Явные действия поднимают поколение до max_seen + 1, checkpoint сохраняет поколение своего сеанса.
      • При переносе поколение поднимает только получатель: max(local, progress_generation) + 1.
      • Уплотнять исходящий журнал можно, только выбрасывая записи, которые перекрыты другой ожидающей записью.
    • ListenSession — G-set по session_id: одно завершение на сеанс, повторная доставка не увеличивает счётчик. Общие пороги: reaches_completion = min(30 с, 5 %) до конца. В историю сеанс попадает при ≥ 30 с прослушивания или при завершении.

RSS/Atom-парсер — podcast::feed, feature podcast-feed

  • Перенесён feed.rs из исходного PR furumi-tui со всеми тестами и всей устойчивостью к ошибкам: кодировки, сущности, кривые теги, лимиты глубины и размера, нестрогие даты.
  • Добавлено: itunes:season, itunes:episode, itunes:episodeType, guid isPermaLink, itunes:new-feed-url, подсказки идентичности, to_meta, to_podcast_meta, resolve_episode_ids.
  • Ссылки (<link>, Atom href) сохраняются как есть, только с обрезкой пробелов: они участвуют в идентичности.
  • Очистка HTML линейна по размеру входа.
  • Зависимости опциональные: quick-xml, encoding_rs, url.

device_sync: протокол v4 (ALPN furumi/sync/2 не меняется)

  • Новые операции: podcast_subscription_set, podcast_share_set, podcast_feed_aliases_added, podcast_progress_set, podcast_listen_recorded.
    • Ни одна из них не tombstone.
    • Материализаторы берут метку из операции: hlc_ms, op_id, origin_device_id. generation берётся из payload.
    • validate_podcast проверяет операцию.
  • Snapshot.
    • Секции podcast_subscriptions (без description), podcast_shares, podcast_progress, podcast_listen_sessions с serde(default). Пустые секции не сериализуются.
    • bound_podcast_state_to(budget): лимиты по количеству и отдельная доля байтового бюджета для каждой секции (25/5/45/25 %, остаток переходит дальше). Подписки не могут вытеснить прогресс.
    • podcast_snapshot_budget(other_bytes) удерживает всю строку в пределах MAX_SYNC_LINE.
    • for_peer(v) убирает секции для пиров ниже v4.
  • Очередь.
    • PlaybackTrack.source: Option<PlaybackSource> = Music | PodcastEpisode(Box<PodcastEpisodeRef>) | Private.
    • PlaybackTrack::podcast_episode(..) — без отрицательных ID и без URL в file_path.
    • Зарезервировано поле PlaybackStateWire.playback_rate.
  • Версия пира.
    • DeviceProfileSet.protocol_version: Option<u16>.
    • Собственный отчёт устройства применяется через profile_protocol_version. Пересланные профили — через relayed_protocol_version: они только повышают версию, потому что развёрнутые v3-клиенты подставляют при пересылке свою константу.
    • InviteWire.protocol_version (ключ p, необязательный) и inviter_protocol_version(): PairRequest отсекается по версии из приглашения, без версии считается v1.
  • Отсечка (gating). op_allowed_for_peer, playback_allowed_for_peer, playback_command_allowed_from_peer, playback_state_has_podcasts, playback_command_has_podcasts.
  • Jam.
    • redact_for_jam и jam::redact_jam_snapshot заменяют выпуски «приватным элементом» без URL, названия и ID.
    • jam_command_allowed отклоняет команды участника с выпусками.
    • restore_jam_private_items возвращает выпуски на место плейсхолдеров при паузе, перемотке и перестановке музыки.

Версии и документация

  • music-dht 0.5.0 → 0.6.0, furumi-library 0.2.0 → 0.3.0. furumi-library реэкспортирует типы music-dht; кода подкастов в нём пока нет.
  • Новый PODCASTS.md — нормативный контракт. В нём разделы о версиях пиров, сопряжении, ограничениях snapshot и правилах прогресса при переносе и уплотнении.
  • Обновлены PLAYBACK_PROTOCOL.md (раздел v4), ARCHITECTURE.md, README.md, README обоих крейтов и CHANGELOG.md.

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

  • В payload новых операций нет собственных hlc/op_id: записи собираются из SyncOpWire, поэтому две метки не могут разойтись. В snapshot лежат полные записи.
  • Поколение Лэмпорта для подписки и публикации. В плане (R4) у этих регистров был чистый LWW по (hlc, op_id). Но hlc_ms у клиентов — настенные часы, которые сдвигаются только своими операциями. Поэтому у подписки и публикации появилось поле generation, общее для двух регистров, как у прогресса. Без него устройство с убежавшими вперёд часами отменяло бы более позднюю отписку.
  • shared = false — не tombstone. Это защищающее приватность состояние. Если его уплотнить, повторно доставленное старое true снова опубликует подкаст.
  • Отдельная операция для алиасов (podcast_feed_aliases_added). Фоновое обновление RSS не может писать в регистр подписки, иначе оно воскресит отписку. Алиасы, которые оно узнаёт, раньше не синхронизировались вовсе.
  • PodcastEpisodeRef.progress_generation: состояние воспроизведения при переносе может прийти раньше операций прогресса отправителя. Без поколения отправителя записи получателя проигрывали бы.
  • Строгая десериализация ID и FeedUrl. Некорректный ID или неканоничный URL отклоняет всё сообщение. Так задокументировано и закреплено тестом. Правила заморожены вместе с доменами v1, а соответствующие контракту клиенты сериализуют только каноничные значения.
  • Для парсера добавлен опциональный url: в исходном PR использовался reqwest::Url, это тот же крейт.
  • В PlaybackSource добавлен вариант Private для Jam. PodcastEpisode хранится в Box (clippy large_enum_variant; музыкальные элементы остаются маленькими).
  • В канонизации пустой путь превращается в /, не-ASCII символы percent-кодируются, не-ASCII хосты отклоняются.
  • В парсере guid — Option (без подмены на URL аудио), даты и длительности — в мс, GUID длиннее 2048 байт считается отсутствующим.
  • Пир без указанной версии считается v1 (UNREPORTED_PROTOCOL_VERSION).
  • URL репозитория в Cargo.toml (gt.hexor.cy/ab/frid) не менялся: он отдаёт 301 на Furumi/frid. Обновить его можно отдельным изменением.

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

  • Протокол синхронизации v4, ALPN прежний. Пустые новые поля и секции не сериализуются, поэтому сообщения без подкастов байт в байт совпадают с v3. Это относится и к приглашениям без p.
  • Старый JSON без source, playback_rate, protocol_version, p и подкастовых секций читается.
  • SyncOpPayload — закрытый enum. Клиент v3 не может разобрать всё сообщение, если в нём есть хотя бы одна новая операция; тест это подтверждает.
  • Поле source клиент v3 просто игнорирует. Он принял бы выпуск за битый музыкальный трек и переслал бы очередь дальше, так что выпуск потерялся бы для всех устройств.
  • Поэтому отсечка по версии обязательна:
    • пирам ниже v4 не отправляются подкастовые операции, секции snapshot и состояние воспроизведения с выпусками;
    • перенос воспроизведения на такой пир запрещается с сообщением «нужно обновление»;
    • их SetState/ActiveChanged отклоняются, пока в очереди есть выпуски;
    • при сопряжении применяется версия из приглашения.
  • Новый вариант PlaybackSource в будущем потребует повышения версии протокола.
  • Postcard-форматы, музыкальный DHT (music-dht-v5), federation-net и content ID не меняются.
  • Изменение ломающее для 0.x: новые варианты enum и поля структур (generation, progress_generation, InviteWire.protocol_version) требуют правок в клиентах там, где структуры создаются явно или match исчерпывающий.

Как проверено (macOS, rustc/cargo 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 падает только на уже существующем замечании: error: using chunks_exact with a constant chunk size --> crates/furumi-library/src/lib.rs:3496:10 (clippy::chunks_exact_to_as_chunks, новый lint clippy 1.100). Этот файл в MR не менялся (git diff --quiet origin/main по нему чистый). Исправлять это нужно отдельным изменением.
    • cargo clippy -p music-dht -p federation-net --all-targets --all-features -- -D warnings — OK.
    • cargo clippy -p music-dht --all-targets -- -D warnings (фичи по умолчанию) — OK.
    • furumi-library с -A clippy::chunks_exact_to_as_chunks — OK.
  • RUSTDOCFLAGS="-D warnings" cargo doc -p music-dht --no-deps (по умолчанию и --all-features) — OK
  • cargo test --workspace — OK: federation-net 31 + 10 интеграционных, furumi-library 30, music-dht 157 + 2 + 3 + 1, doctest-ы 1/0/4.
    • При первом прогоне интеграционный iroh-тест library_sync_and_distributed_search упал по таймауту. Повторный и оба остальных полных прогона прошли. Изменения сетевой код не затрагивают.
  • cargo test --workspace --features music-dht/podcast-feed — OK (music-dht lib 182, doctest-ы music_dht 5).
  • cargo test --workspace --all-features — OK, те же числа.
  • Интеграционные тесты используют настоящие iroh-соединения через сеть.
  • Тесты:
    • все перестановки наборов операций и законы слияния (коммутативность, ассоциативность, идемпотентность);
    • поздний checkpoint старого поколения проигрывает; «Начать сначала» побеждает поздний checkpoint;
    • параллельные офлайн-сеансы сходятся, оба сеанса сохраняются;
    • отписка переживает возвращение офлайн-устройства; повторная подписка сохраняет прогресс; обновление RSS не трогает прогресс;
    • сдвиг часов на +10 мин не отменяет увиденную отписку; «Поделиться» после подписки действует при сдвиге часов; shared = false с большим поколением побеждает все устаревшие true;
    • перенос: получатель с поколением отправителя побеждает его checkpoint; уплотнение сохраняет «mark played», а не поздний checkpoint;
    • текущий feed_url разрешается за пределами ограничения на алиасы;
    • golden-значение и формула ID, канонизация URL, опечатки https:/, правило без GUID;
    • результат не зависит от порядка элементов; сильное совпадение по enclosure не уступает слабому;
    • ссылки сохраняются как есть;
    • очистка текста линейна: около 262 тыс. <a в двух полях обрабатываются меньше чем за 2 с даже в debug;
    • JSON v3 читается; enum в форме v3 отклоняет пакет с новой операцией; некорректный ID или URL отклоняет всё сообщение;
    • границы отсечки v3/v4; пересланная версия 3 не понижает v4; приглашение без версии отсекает PairRequest;
    • редакция Jam: в JSON нет названий, URL и ID;
    • лимиты snapshot: ровно на лимите и первое значение за ним, раздельный байтовый бюджет, прогресс не вытесняется подписками, бюджет как параметр.

Ограничения

  • Проверено только на macOS. Клиенты используют контракт в MR-T2/T3 и MR-W1–W3. Межклиентские сценарии прошли в составе всего стека (см. «Межклиентская проверка»), а не на этой ветке отдельно.
  • Если два устройства офлайн подписались на одну ленту по разным URL до синхронизации алиаса, получатся два PodcastId. Автоматическое слияние ID в этой версии не определено. Если у подкаста больше 8 алиасов, бо́льшие URL могут выпасть из синхронизируемого множества.
  • Выпуски без GUID: ID может зависеть от того, что устройство видело раньше. Достаточно изменить одно поле, из которого был выведен ID (<link>, либо название или дату). Относительные enclosure разрешаются относительно URL загрузки, поэтому у устройств, загружающих ленту через разные алиасы, ключи могут различаться.
  • Устройство, обновившееся с v3 или получавшее операции через v3-реле, восстанавливает из snapshot только самые новые записи в пределах лимитов. Старый прогресс и сеансы сверх лимитов на нём не появятся, и счётчики прослушиваний могут отличаться от других устройств. Агрегат «число завершений на выпуск» в snapshot не добавлялся.
  • При двух одновременных записях без взаимной видимости (одинаковое поколение) порядок по-прежнему решают часы.
  • Понижение версии устройства ниже v4 не поддерживается, пока реле хранят для него v4.
  • Явное удаление личной истории не определено. Публичные карточки и поиск (MR-F3) в этот MR не входят. playback_rate только зарезервирован.

Зависимости

  • Ни от каких MR не зависит.
  • От него зависят MR-F2 (PodcastStore в furumi-library), MR-T2 (TUI), MR-W1 и MR-W2 (веб), MR-F3 (podcast_dht). Клиентам нужно:
    • заполнять generation через next_podcast_generation;
    • выпускать podcast_feed_aliases_added;
    • ставить progress_generation в элементы очереди;
    • различать собственные и пересланные профили;
    • класть версию в приглашение.
  • Ветка Sanapach/frid:podcasts/contract → Furumi/frid:main (база b191c10, вершина 65d6ca2). Семь коммитов (git log --oneline main..podcasts/contract):
    • 38e49c4 Add shared podcast contract to music-dht
    • 31d132b Add podcast-feed RSS and Atom parser
    • 2d47828 Add podcasts to device-sync protocol v4
    • 4f7e999 Document podcast contract and bump crate versions
    • 629857d Make podcast episode identity order-independent and linear
    • 085bff6 Harden podcast sync registers, versions and snapshots
    • 65d6ca2 Document podcast register ordering, versions and snapshot limits

Cargo.lock и [patch]

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

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

Контракт этого MR проверен в составе всего стека (TUI 0.5.0 + веб 0.15.0 + выпущенные TUI 0.3.5 и веб 0.12.4, frid podcasts/discovery @ 9c82f6d). Все сценарии TUI ↔ TUI (23 проверки) и TUI ↔ веб (37 pass, 0 fail) прошли, включая отсечку v3/v4 и редакцию Jam. Не прогонялись: прокси веба с локальным издателем и Jam с хостом-TUI и гостем-вебом (причины и таблица — в MR-T2 и MR-W2). Отдельно на ветке podcasts/contract межклиентских прогонов не было.

🤖 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 и зависимости — в разделе зависимостей ниже. ## Что сделано Первый MR серии «Подкасты» (MR-F1 из `PODCASTS_PLAN.md`). В FRID добавлен общий контракт подкастов. На него опираются все следующие MR: F2, T2, W1, W2, F3. ### `music_dht::podcast` — чистый модуль без SQLite, HTTP и часов - **Идентичность.** - `FeedUrl` — каноничный URL ленты. - Схема и хост приводятся к нижнему регистру. - Порт по умолчанию и фрагмент убираются. - Путь и **вся** строка запроса сохраняются байт в байт. - Отклоняются не-http(s), userinfo, пробелы, `\` и не-ASCII хост (нужна форма `xn--`). - `FeedUrl::from_user_input` разбирает пользовательский ввод: `feed:`, `podcast:`, `pcast:`, `itpc:` и URL без схемы. Опечатки вида `https:/host` отклоняются. - `PodcastId = "pod1:" + base32(BLAKE3("furumi-podcast:podcast:v1\0" + url))`. ID вычисляется по URL первой подписки. - `EpisodeId = "ep1:" + base32(BLAKE3("furumi-podcast:episode:v1\0" + podcast_id + key))`. Ключи: `guid:`, `link:`, `date-title:`, `enclosure:`. - **Правило без GUID** (`resolve_episode_ids`, нормативное). - Выпуск с GUID получает ID по GUID. - Выпуски без GUID сопоставляются с уже известными в три этапа по всему документу: по enclosure, затем по `<link>`, затем по паре (дата, нормализованное название). Каждый этап отрабатывает для всех выпусков, прежде чем начнётся следующий, поэтому результат не зависит от порядка элементов в ленте. - Если совпадения нет, новый ID строится по первому доступному ключу: link → дата+название → enclosure. - Ссылки, которые повторяются в ленте или совпадают со ссылкой канала, выпуск не идентифицируют. - **Алиасы ленты.** - `merge_feed_aliases` — ограниченное grow-only множество: исходный URL плюс 8 лексикографически наименьших. - `SubscriptionRecord::feed_urls()` — алиасы плюс текущий `podcast.feed_url`. Он участвует в `resolve_podcast_id`, даже если не поместился в ограничение множества. - **DTO.** - `PodcastMeta`, `EpisodeMeta`: сезон, номер, `episodeType`, длительность и дата в мс, URL аудио, MIME, размер, обложка, ссылка. - `PodcastEpisodeRef` — самодостаточный и ограниченный элемент очереди. Необязательное поле `progress_generation` — подсказка для переноса воспроизведения. - Валидация границ: заголовок до 1000 символов, описание до 4000, URL до 2048 байт. - **Правила слияния.** Все функции коммутативны, ассоциативны и идемпотентны. Ничьи разрешаются полным порядком. - `SubscriptionRecord` и `ShareRecord` — LWW по `(generation, hlc_ms, op_id)`. - `generation` — счётчик Лэмпорта для подкаста, один на оба регистра: `next_podcast_generation` = max + 1. - Действие, совершённое после того, как устройство увидело чужую запись, побеждает её при любых часах. - Отписка и `shared = false` — состояние, а не tombstone. Они никогда не уплотняются. - Прогресс и история при отписке сохраняются. - `effective_share`: публикация действует, только если решение «Поделиться» упорядочено после последней записи подписки. - `ProgressRecord` — регистр с порядком `(generation, hlc_ms, device_id, op_id)`. - Явные действия поднимают поколение до `max_seen + 1`, checkpoint сохраняет поколение своего сеанса. - При переносе поколение поднимает только получатель: `max(local, progress_generation) + 1`. - Уплотнять исходящий журнал можно, только выбрасывая записи, которые перекрыты другой ожидающей записью. - `ListenSession` — G-set по `session_id`: одно завершение на сеанс, повторная доставка не увеличивает счётчик. Общие пороги: `reaches_completion` = min(30 с, 5 %) до конца. В историю сеанс попадает при ≥ 30 с прослушивания или при завершении. ### RSS/Atom-парсер — `podcast::feed`, feature `podcast-feed` - Перенесён `feed.rs` из исходного PR furumi-tui со всеми тестами и всей устойчивостью к ошибкам: кодировки, сущности, кривые теги, лимиты глубины и размера, нестрогие даты. - Добавлено: `itunes:season`, `itunes:episode`, `itunes:episodeType`, `guid isPermaLink`, `itunes:new-feed-url`, подсказки идентичности, `to_meta`, `to_podcast_meta`, `resolve_episode_ids`. - Ссылки (`<link>`, Atom `href`) сохраняются как есть, только с обрезкой пробелов: они участвуют в идентичности. - Очистка HTML линейна по размеру входа. - Зависимости опциональные: `quick-xml`, `encoding_rs`, `url`. ### `device_sync`: протокол v4 (ALPN `furumi/sync/2` не меняется) - **Новые операции:** `podcast_subscription_set`, `podcast_share_set`, `podcast_feed_aliases_added`, `podcast_progress_set`, `podcast_listen_recorded`. - Ни одна из них не tombstone. - Материализаторы берут метку из операции: `hlc_ms`, `op_id`, `origin_device_id`. `generation` берётся из payload. - `validate_podcast` проверяет операцию. - **Snapshot.** - Секции `podcast_subscriptions` (без `description`), `podcast_shares`, `podcast_progress`, `podcast_listen_sessions` с `serde(default)`. Пустые секции не сериализуются. - `bound_podcast_state_to(budget)`: лимиты по количеству и отдельная доля байтового бюджета для каждой секции (25/5/45/25 %, остаток переходит дальше). Подписки не могут вытеснить прогресс. - `podcast_snapshot_budget(other_bytes)` удерживает всю строку в пределах `MAX_SYNC_LINE`. - `for_peer(v)` убирает секции для пиров ниже v4. - **Очередь.** - `PlaybackTrack.source: Option<PlaybackSource>` = `Music` | `PodcastEpisode(Box<PodcastEpisodeRef>)` | `Private`. - `PlaybackTrack::podcast_episode(..)` — без отрицательных ID и без URL в `file_path`. - Зарезервировано поле `PlaybackStateWire.playback_rate`. - **Версия пира.** - `DeviceProfileSet.protocol_version: Option<u16>`. - Собственный отчёт устройства применяется через `profile_protocol_version`. Пересланные профили — через `relayed_protocol_version`: они только повышают версию, потому что развёрнутые v3-клиенты подставляют при пересылке свою константу. - `InviteWire.protocol_version` (ключ `p`, необязательный) и `inviter_protocol_version()`: `PairRequest` отсекается по версии из приглашения, без версии считается v1. - **Отсечка (gating).** `op_allowed_for_peer`, `playback_allowed_for_peer`, `playback_command_allowed_from_peer`, `playback_state_has_podcasts`, `playback_command_has_podcasts`. - **Jam.** - `redact_for_jam` и `jam::redact_jam_snapshot` заменяют выпуски «приватным элементом» без URL, названия и ID. - `jam_command_allowed` отклоняет команды участника с выпусками. - `restore_jam_private_items` возвращает выпуски на место плейсхолдеров при паузе, перемотке и перестановке музыки. ### Версии и документация - `music-dht` 0.5.0 → **0.6.0**, `furumi-library` 0.2.0 → **0.3.0**. furumi-library реэкспортирует типы music-dht; кода подкастов в нём пока нет. - Новый **`PODCASTS.md`** — нормативный контракт. В нём разделы о версиях пиров, сопряжении, ограничениях snapshot и правилах прогресса при переносе и уплотнении. - Обновлены `PLAYBACK_PROTOCOL.md` (раздел v4), `ARCHITECTURE.md`, `README.md`, README обоих крейтов и `CHANGELOG.md`. ## Решения и отступления от плана - В payload новых операций нет собственных `hlc`/`op_id`: записи собираются из `SyncOpWire`, поэтому две метки не могут разойтись. В snapshot лежат полные записи. - **Поколение Лэмпорта для подписки и публикации.** В плане (R4) у этих регистров был чистый LWW по `(hlc, op_id)`. Но `hlc_ms` у клиентов — настенные часы, которые сдвигаются только своими операциями. Поэтому у подписки и публикации появилось поле `generation`, общее для двух регистров, как у прогресса. Без него устройство с убежавшими вперёд часами отменяло бы более позднюю отписку. - **`shared = false` — не tombstone.** Это защищающее приватность состояние. Если его уплотнить, повторно доставленное старое `true` снова опубликует подкаст. - **Отдельная операция для алиасов** (`podcast_feed_aliases_added`). Фоновое обновление RSS не может писать в регистр подписки, иначе оно воскресит отписку. Алиасы, которые оно узнаёт, раньше не синхронизировались вовсе. - `PodcastEpisodeRef.progress_generation`: состояние воспроизведения при переносе может прийти раньше операций прогресса отправителя. Без поколения отправителя записи получателя проигрывали бы. - **Строгая десериализация ID и `FeedUrl`.** Некорректный ID или неканоничный URL отклоняет всё сообщение. Так задокументировано и закреплено тестом. Правила заморожены вместе с доменами `v1`, а соответствующие контракту клиенты сериализуют только каноничные значения. - Для парсера добавлен опциональный `url`: в исходном PR использовался `reqwest::Url`, это тот же крейт. - В `PlaybackSource` добавлен вариант `Private` для Jam. `PodcastEpisode` хранится в `Box` (clippy `large_enum_variant`; музыкальные элементы остаются маленькими). - В канонизации пустой путь превращается в `/`, не-ASCII символы percent-кодируются, не-ASCII хосты отклоняются. - В парсере `guid` — `Option` (без подмены на URL аудио), даты и длительности — в мс, GUID длиннее 2048 байт считается отсутствующим. - Пир без указанной версии считается v1 (`UNREPORTED_PROTOCOL_VERSION`). - URL репозитория в `Cargo.toml` (`gt.hexor.cy/ab/frid`) не менялся: он отдаёт 301 на `Furumi/frid`. Обновить его можно отдельным изменением. ## Совместимость - Протокол синхронизации v4, ALPN прежний. Пустые новые поля и секции не сериализуются, поэтому сообщения без подкастов байт в байт совпадают с v3. Это относится и к приглашениям без `p`. - Старый JSON без `source`, `playback_rate`, `protocol_version`, `p` и подкастовых секций читается. - `SyncOpPayload` — закрытый enum. Клиент v3 не может разобрать **всё** сообщение, если в нём есть хотя бы одна новая операция; тест это подтверждает. - Поле `source` клиент v3 просто игнорирует. Он принял бы выпуск за битый музыкальный трек и переслал бы очередь дальше, так что выпуск потерялся бы для всех устройств. - Поэтому отсечка по версии обязательна: - пирам ниже v4 не отправляются подкастовые операции, секции snapshot и состояние воспроизведения с выпусками; - перенос воспроизведения на такой пир запрещается с сообщением «нужно обновление»; - их `SetState`/`ActiveChanged` отклоняются, пока в очереди есть выпуски; - при сопряжении применяется версия из приглашения. - Новый вариант `PlaybackSource` в будущем потребует повышения версии протокола. - Postcard-форматы, музыкальный DHT (`music-dht-v5`), `federation-net` и content ID не меняются. - Изменение ломающее для 0.x: новые варианты enum и поля структур (`generation`, `progress_generation`, `InviteWire.protocol_version`) требуют правок в клиентах там, где структуры создаются явно или `match` исчерпывающий. ## Как проверено (macOS, rustc/cargo 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` падает **только** на уже существующем замечании: `error: using chunks_exact with a constant chunk size --> crates/furumi-library/src/lib.rs:3496:10` (`clippy::chunks_exact_to_as_chunks`, новый lint clippy 1.100). Этот файл в MR не менялся (`git diff --quiet origin/main` по нему чистый). Исправлять это нужно отдельным изменением. - `cargo clippy -p music-dht -p federation-net --all-targets --all-features -- -D warnings` — OK. - `cargo clippy -p music-dht --all-targets -- -D warnings` (фичи по умолчанию) — OK. - furumi-library с `-A clippy::chunks_exact_to_as_chunks` — OK. - `RUSTDOCFLAGS="-D warnings" cargo doc -p music-dht --no-deps` (по умолчанию и `--all-features`) — OK - `cargo test --workspace` — OK: federation-net 31 + 10 интеграционных, furumi-library 30, music-dht 157 + 2 + 3 + 1, doctest-ы 1/0/4. - При первом прогоне интеграционный iroh-тест `library_sync_and_distributed_search` упал по таймауту. Повторный и оба остальных полных прогона прошли. Изменения сетевой код не затрагивают. - `cargo test --workspace --features music-dht/podcast-feed` — OK (music-dht lib 182, doctest-ы music_dht 5). - `cargo test --workspace --all-features` — OK, те же числа. - Интеграционные тесты используют настоящие iroh-соединения через сеть. - Тесты: - все перестановки наборов операций и законы слияния (коммутативность, ассоциативность, идемпотентность); - поздний checkpoint старого поколения проигрывает; «Начать сначала» побеждает поздний checkpoint; - параллельные офлайн-сеансы сходятся, оба сеанса сохраняются; - отписка переживает возвращение офлайн-устройства; повторная подписка сохраняет прогресс; обновление RSS не трогает прогресс; - сдвиг часов на +10 мин не отменяет увиденную отписку; «Поделиться» после подписки действует при сдвиге часов; `shared = false` с большим поколением побеждает все устаревшие `true`; - перенос: получатель с поколением отправителя побеждает его checkpoint; уплотнение сохраняет «mark played», а не поздний checkpoint; - текущий `feed_url` разрешается за пределами ограничения на алиасы; - golden-значение и формула ID, канонизация URL, опечатки `https:/`, правило без GUID; - результат не зависит от порядка элементов; сильное совпадение по enclosure не уступает слабому; - ссылки сохраняются как есть; - очистка текста линейна: около 262 тыс. `<a` в двух полях обрабатываются меньше чем за 2 с даже в debug; - JSON v3 читается; enum в форме v3 отклоняет пакет с новой операцией; некорректный ID или URL отклоняет всё сообщение; - границы отсечки v3/v4; пересланная версия 3 не понижает v4; приглашение без версии отсекает `PairRequest`; - редакция Jam: в JSON нет названий, URL и ID; - лимиты snapshot: ровно на лимите и первое значение за ним, раздельный байтовый бюджет, прогресс не вытесняется подписками, бюджет как параметр. ## Ограничения - Проверено только на macOS. Клиенты используют контракт в MR-T2/T3 и MR-W1–W3. Межклиентские сценарии прошли в составе всего стека (см. «Межклиентская проверка»), а не на этой ветке отдельно. - Если два устройства офлайн подписались на одну ленту по разным URL до синхронизации алиаса, получатся два `PodcastId`. Автоматическое слияние ID в этой версии не определено. Если у подкаста больше 8 алиасов, бо́льшие URL могут выпасть из синхронизируемого множества. - Выпуски без GUID: ID может зависеть от того, что устройство видело раньше. Достаточно изменить одно поле, из которого был выведен ID (`<link>`, либо название или дату). Относительные enclosure разрешаются относительно URL загрузки, поэтому у устройств, загружающих ленту через разные алиасы, ключи могут различаться. - Устройство, обновившееся с v3 или получавшее операции через v3-реле, восстанавливает из snapshot только самые новые записи в пределах лимитов. Старый прогресс и сеансы сверх лимитов на нём не появятся, и счётчики прослушиваний могут отличаться от других устройств. Агрегат «число завершений на выпуск» в snapshot не добавлялся. - При двух одновременных записях без взаимной видимости (одинаковое поколение) порядок по-прежнему решают часы. - Понижение версии устройства ниже v4 не поддерживается, пока реле хранят для него v4. - Явное удаление личной истории не определено. Публичные карточки и поиск (MR-F3) в этот MR не входят. `playback_rate` только зарезервирован. ## Зависимости - Ни от каких MR не зависит. - От него зависят MR-F2 (`PodcastStore` в furumi-library), MR-T2 (TUI), MR-W1 и MR-W2 (веб), MR-F3 (`podcast_dht`). Клиентам нужно: - заполнять `generation` через `next_podcast_generation`; - выпускать `podcast_feed_aliases_added`; - ставить `progress_generation` в элементы очереди; - различать собственные и пересланные профили; - класть версию в приглашение. - Ветка `Sanapach/frid:podcasts/contract` → `Furumi/frid:main` (база `b191c10`, вершина `65d6ca2`). Семь коммитов (`git log --oneline main..podcasts/contract`): - `38e49c4` Add shared podcast contract to music-dht - `31d132b` Add podcast-feed RSS and Atom parser - `2d47828` Add podcasts to device-sync protocol v4 - `4f7e999` Document podcast contract and bump crate versions - `629857d` Make podcast episode identity order-independent and linear - `085bff6` Harden podcast sync registers, versions and snapshots - `65d6ca2` Document podcast register ordering, versions and snapshot limits ## `Cargo.lock` и `[patch]` - В самом frid `[patch]` нет: `Cargo.lock` workspace-а обновлён этим MR вместе с версиями крейтов. - Клиенты пока собираются против этой ветки через локальный `.cargo/config.toml` с `[patch.crates-io]` на пути к рабочей копии. Этот файл исключён из git и в коммиты не попадает. Перед merge клиентских MR их `Cargo.lock` перегенерируется: сначала против запушенной ветки форка (git-зависимость `https://gt.hexor.cy/Sanapach/frid.git`, последний коммит каждого клиентского MR — «Point frid deps at the fork branch»), а после публикации `music-dht 0.6.0` и `furumi-library 0.3.0` — против крейтов с crates.io (`[patch]` удаляется). На этот MR (`podcasts/contract`) указывают MR-W1 и MR-W2. ## Межклиентская проверка Контракт этого MR проверен в составе всего стека (TUI 0.5.0 + веб 0.15.0 + выпущенные TUI 0.3.5 и веб 0.12.4, frid `podcasts/discovery` @ `9c82f6d`). Все сценарии TUI ↔ TUI (23 проверки) и TUI ↔ веб (37 pass, 0 fail) прошли, включая отсечку v3/v4 и редакцию Jam. Не прогонялись: прокси веба с локальным издателем и Jam с хостом-TUI и гостем-вебом (причины и таблица — в MR-T2 и MR-W2). Отдельно на ветке `podcasts/contract` межклиентских прогонов не было. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
sanapach added 7 commits 2026-11-20 13:21:59 +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>
sanapach changed title from Podcasts/contract to Подкасты в FRID: общий контракт music_dht::podcast, RSS-парсер и device-sync v4 (MR-F1) 2026-11-20 13:30:37 +00:00
ab merged commit ddea053e9d into main 2026-11-20 13:51:49 +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#1