Document fair publication limits, share states and moved feeds

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-20 15:12:52 +02:00
1 parent 12617a6d52
commit 4b45aa5805
3 files changed
+93 -29

No files matched your search

+13 -4
View File
@@ -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
+39 -9
View File
@@ -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
+41 -16
View File
@@ -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`.