From 4b45aa58059687495b10d7e24c654ed22985d113 Mon Sep 17 00:00:00 2001 From: Sanapach Date: Fri, 20 Nov 2026 00:07:22 +0200 Subject: [PATCH] Document fair publication limits, share states and moved feeds Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 17 ++++++++++--- docs/administration.md | 48 ++++++++++++++++++++++++++++------- docs/development.md | 57 ++++++++++++++++++++++++++++++------------ 3 files changed, 93 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 948dd7b..5b2154f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,11 +7,15 @@ (`federation.podcast` events, `"type": "podcast"`; music events are unchanged and now carry `"type": "music"`), with **Already subscribed** when you follow the podcast, also under another feed address. A card - opens with its metadata and the seasons and episodes read from the feed - (`POST /api/podcasts/discovery/preview`), and **Subscribe** + opens with its metadata and the seasons and episodes read from the feed, + browsable by season (`POST /api/podcasts/discovery/preview`), and + **Subscribe** (`POST /api/podcasts/discovery/subscribe`) creates your own private subscription from the card's original feed address with the card's - podcast id; the publishing member is never contacted. Card texts and + podcast id, or your existing podcast when you already follow the feed + under the address it moved to (also for **Add RSS**); the publishing + member is never contacted. A failed podcast search keeps the music + results and says so. Card texts and links are untrusted: shown as text, links and artwork only as checked `http(s)` (artwork `https`) addresses. - Share a podcast in the federation: a **Share in the federation** toggle on @@ -27,7 +31,12 @@ `furumusic__podcast_share_confirmation`) and asked again for a new share decision or a moved feed. Accounts sharing the same podcast share one card, published while any of them shares it; at most 192 podcasts per - server. New endpoint `POST /api/podcasts/feeds/{id}/share` + server, shared fairly between the sharing accounts (an account within + its part never loses a published card to other accounts). The podcast + page says whether this server published the card, waits for a + confirmation, holds it back at the limit, or cannot publish because + federation is off or discovery is unavailable; the list marks + **Sharing on**. New endpoint `POST /api/podcasts/feeds/{id}/share` (`{"shared": bool, "confirm"?: {...}}`, 409 when a confirmation is needed); `GET /api/podcasts/feeds/{id}` reports the share state. - The federation node serves the podcast-discovery overlay diff --git a/docs/administration.md b/docs/administration.md index 656eb1c..7895353 100644 --- a/docs/administration.md +++ b/docs/administration.md @@ -144,14 +144,34 @@ your progress, history, listening counts, device names or your account. node key that publishes its music library), not with an identity of your account. When several accounts of this server share the same podcast, the server publishes one card for it, built from one of these accounts' - copies of the public feed, and keeps it while any of them still shares - it. Other members see that this server shares the podcast, not who. - Podcasts shared by a deactivated account are no longer published (within - five minutes). + copies of the feed (preferably one the server downloaded itself, and the + same account as long as it keeps sharing, so another account sharing the + podcast later does not replace the card's text), and keeps it while any + of them still shares it. Other members see that this server shares the + podcast, not who. Podcasts shared by a deactivated account are no longer + published (within five minutes). +- The podcast page says what this server does with the card: published, + publishing, waiting for your confirmation, held back by the server's + limit, or not possible because federation is off or public discovery is + unavailable. It shows only this server's publication: a Furumi player + such as the terminal player publishes its own card with its own identity + when you share there, so the card may be public through that player + while this server still waits for your confirmation. The podcast list + marks a podcast with **Sharing on** when your decision is to share it. - Publishing needs federation to be enabled on the server (Settings → Federation). Without it, the share decision is kept and the card is - published once federation runs. A server publishes at most 192 podcasts; - podcasts shared later wait until others are revoked. + published once federation runs. +- A server publishes at most 192 podcasts, shared fairly between the + accounts that share podcasts: every account gets its turn in rotation, + so an account whose shared podcasts fit in its part of the limit (192 + divided by the number of sharing accounts) never loses a published card + because other accounts share many podcasts. When the limit is reached, + only podcasts of accounts beyond their part wait (newest shares first; + cards already published are kept before new ones), and the podcast page + says that the card is held back. +- A podcast whose stored data cannot be read (for example after a damaged + import) is treated as not shared, and its card is revoked; the other + podcasts are still published and revoked as usual. - Revoking is eventually consistent: the server publishes a signed revocation at once, but a federation peer that missed it may show the old card for up to 12 hours. Subscriptions other members made from the card @@ -171,11 +191,19 @@ and `podcast_discovery_peers`. The search box searches the federation too. Podcasts that members shared appear under **Federation → Podcasts**, marked **Podcast** and kept apart from music; podcasts you already follow are marked **Already subscribed** -(also when you follow the same feed under an older or newer address). +(also when you follow the same feed under an older address it moved +from). If you follow the feed only under the newer address of a card's +moved feed, the result list cannot tell yet; opening the card reads the +feed, sees the move and shows **Already subscribed** with **Open**, and +neither **Subscribe** nor **Add RSS** with the old address creates a +second subscription. - Opening a card shows its title, author, description, artwork and the feed URL, then loads the seasons and episodes from the feed itself through the - server. Nothing is stored until you subscribe. + server: the newest 50 episodes, and the newest 50 of one season when you + pick its chip (pick it again for all seasons). Nothing is stored until + you subscribe. Closing the card, or picking another season, cancels a + loading preview. - **Subscribe** adds your own private subscription: the server downloads the feed from the card's address, as for **Add RSS**, and you can then play, share or unsubscribe it like any other. The member who published the card @@ -192,7 +220,9 @@ from music; podcasts you already follow are marked **Already subscribed** account are ever visible. A card disappears from search results within 12 hours after it is revoked. - Podcast search needs federation on this server. When public discovery is - off or unavailable, the search shows music only. + off or unavailable, the search shows music only. When the podcast search + fails or times out, the music results are still shown, with a note that + the podcast search did not answer. ### Podcast feeds and audio diff --git a/docs/development.md b/docs/development.md index 90ed61a..9771e1a 100644 --- a/docs/development.md +++ b/docs/development.md @@ -233,21 +233,39 @@ only while the overlay runs. account's catalog fetch URL as `feed_url`, the origin URL as `id_feed_url` and the feed's episode count and newest date. - `load_shared` reads active accounts only (`furumusic__user.is_active`). + An `(account, podcast)` whose stored data does not decode (a URL, the + register JSON, an id) is left out and counted (`unreadable`): only a + failing connection or query skips the round, so revocation stays + fail-safe for each podcast on its own. - `aggregate_share_states` keeps the accounts for which `effective_share` holds and whose card has no privacy warnings or a matching confirmation, - and builds one `PodcastShareState` per podcast (representative: no - warnings first, then the smallest account id) with - `privacy_confirmed = true`; at most 192 podcasts (replicas keep 256 - records per publisher, tombstones included). `PodcastDht::sync_shares` - publishes them and tombstones everything else. + and builds one `PodcastShareState` per podcast with + `privacy_confirmed = true`. Representative: no warnings, then a catalog + from the server's own fetch (`meta_from_feed`), then the previous + round's representative (kept in memory), then the smallest account id. +- At most 192 podcasts (replicas keep 256 records per publisher, tombstones + included), allocated round-robin over the sharing accounts (`allocate`): + each account's queue holds its podcasts the node already publishes + first, then by its own share time; in every round each account takes its + next podcast not taken yet, published ones first inside a round. An + account's share times therefore only order its own podcasts. + `PodcastDht::sync_shares` publishes the result and tombstones everything + else. The podcasts left out (`over_limit`) and those `sync_shares` + reported as failed are kept in memory for `ShareView.held`. - `furumusic__podcast_share_confirmation` (`m_0058`) is the client-held `privacy_confirmed`: per account and podcast, bound to the share register's `op_id` and the exact card URLs. Never synced. - The reconciler runs on `discovery::request_reconcile()` (after local share, subscribe and unsubscribe actions, received subscription/share/alias operations and snapshot sections, refreshes of shared podcasts; 2 s - debounce) and every five minutes. Database errors skip a round. Only - counts are logged. + debounce) and every five minutes. Connection and query errors skip a + round. Only counts are logged. +- `ShareView` (in `GET /api/podcasts/feeds/{id}` and the share response): + `discovery` is `running`, `unavailable` (the node runs, the overlay did + not start; `Federation::podcast_discovery_unavailable`) or `off`; + `published` is this server node's own active card only; `held` is + `over_limit` or `failed` after the last round. An unreadable overlay + cache degrades to `published: false` instead of failing the page. - `POST /api/podcasts/feeds/{id}/share` requires a JSON body (`{"shared": bool, "confirm"?: {"feed_url", "id_feed_url"}}`); a card with warnings is shared only with `confirm` naming exactly its current URLs @@ -266,17 +284,24 @@ Search and subscription from a card (`src/podcasts/search.rs`): with the music items, and the searching account's `subscribed` / `local_podcast_id` (by id, or a known feed URL or alias through `resolve_podcast_id`). `search.completed` adds `podcast_discovery` - (`running`, `off`, `failed`); a failed podcast search never fails the - music search. + (`running`, `off`, `failed`); a failed podcast search, or a failure to + prepare its hits for the account (`Federation::podcast_search_events` + never fails), only drops the podcast hits and reports `failed`. - `POST /api/podcasts/discovery/preview` and `/discovery/subscribe` take `{"podcast_id", "feed_url"}` from a hit and refuse a URL the id does not - hash from (422). The preview fetches the feed through the SSRF-guarded - fetcher and returns the channel, season counts and the newest 50 episodes - without storing anything; subscribe runs `runner::subscribe_url` with the - origin URL (fetch first, then a private subscription with the card's id, - or the account's existing podcast for a known URL), and writes nothing - when the account is already subscribed. Both share the "add RSS" request - limits. + hash from (422). The preview (optional `"season"`: a number as a + string, `"none"` or `"all"`) fetches the feed through the SSRF-guarded + fetcher and returns the channel, season counts, `listed_count` and the + newest 50 episodes of the season, without storing anything; subscribe + fetches the origin URL, then `runner::subscribe_fetched` writes a + private subscription with the card's id, or the account's existing + podcast for the first known URL of `runner::document_urls` (the origin, + the end of a permanent redirect chain, the feed's `itunes:new-feed-url`; + also used by "add RSS"). Nothing is written when the account is already + subscribed, by id or known URL, before or after the fetch. Both share + the "add RSS" request limits; the browser aborts a preview it no longer + shows (`AbortController`), so a closed card frees its slot once the + server sees the connection close. - The browser keeps only expected, typed card fields (`podcasts.foundHit`): ids must look like podcast ids, URLs must be absolute `http(s)` without credentials (artwork: `https` only), and texts render with `x-text`.