From 27fc2c5354aa00e5881fbcd69278443791e66760 Mon Sep 17 00:00:00 2001 From: Sanapach Date: Thu, 19 Nov 2026 23:12:21 +0200 Subject: [PATCH] Document public podcast discovery in the web server Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 24 +++++++++++++++++ docs/administration.md | 58 ++++++++++++++++++++++++++++++++++++++---- docs/development.md | 41 +++++++++++++++++++++++++++++ 3 files changed, 118 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3f351db..80ac20d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,29 @@ # Changelog +## Unreleased + +- Share a podcast in the federation: a **Share in the federation** toggle on + the podcast page publishes a public card of the podcast (title, author, + description, artwork, feed URL, episode count; never progress, history, + devices or the account) through the server's federation node on the + separate `podcast_dht` overlay of `music-dht` 0.6. Sharing is the + account's synchronized decision; turning it off or unsubscribing on any + device revokes it, and a late state of another device cannot publish it + again. A feed URL that looks private (token or key in the address, a + member-feed host) needs a confirmation of the exact address first; the + confirmation is local to the server (`m_0058`, + `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` + (`{"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 + (`furumi-fd/podcast-dht/1`, cache `podcast-dht.sqlite3` in the federation + data directory), advertises `podcast_dht` in its capability manifest only + while it runs, and probes peers' manifests so the overlay skips peers + without it. If the overlay cannot start, only discovery is disabled. + ## v0.14.0 — 2026-11-19 - Podcasts in the web player: a Podcasts section to add RSS feeds, browse diff --git a/docs/administration.md b/docs/administration.md index 90e86c1..0887bb8 100644 --- a/docs/administration.md +++ b/docs/administration.md @@ -112,11 +112,59 @@ for unplayed, started and played episodes, and the recent listening history. Privacy: a new subscription is private. Subscriptions, progress and listening history are synchronized only between your own paired Furumi players (trusted devices), never published to the federation, and Jam guests cannot see your -episodes. Publishing a podcast for discovery is not available in the web -player yet. Episodes are not stored on the server or shared with peers: the -browser streams the audio and loads the artwork directly from the publisher, -so the publisher sees your browser's address. With the audio proxy (below) -the publisher sees the server instead. +episodes. Only podcasts you share explicitly are published (see below). +Episodes are not stored on the server or shared with peers: the browser +streams the audio and loads the artwork directly from the publisher, so the +publisher sees your browser's address. With the audio proxy (below) the +publisher sees the server instead. + +### Sharing a podcast in the federation + +**Share in the federation** on a podcast page publishes a public card of the +podcast so that members of the federation network outside your own devices +can find it and subscribe. The card holds only the podcast's public +metadata: title, author, description, artwork and site links, the feed URL, +the number of episodes and the newest publication date. It never contains +your progress, history, listening counts, device names or your account. +**Stop sharing** or **Unsubscribe** revokes it; your progress is kept. + +- Sharing is your decision and is synchronized with your other Furumi + players, like the subscription. A podcast shared on another player is + shared here too, and turning it off anywhere turns it off everywhere. A + new subscription, including subscribing again, is always private. +- If the feed URL looks like it may contain private data (an access token or + key in the address, a host of personal subscriber feeds, a long random + part), the web player shows a confirmation dialog with the exact address + before publishing it. Such feeds are often personal: publishing one can + let others use your access. The confirmation belongs to this server and to + this one decision; it is asked again when you share again, when the feed + moves to another address, and when sharing was turned on on another + player. +- The **server** publishes the card with its federation identity (the same + 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). +- 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. +- 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 + stay theirs. + +The server joins the separate podcast-discovery overlay +(`furumi-fd/podcast-dht/1`) of the federation network and keeps its routing +contacts and the cards it holds for others in `podcast-dht.sqlite3` in the +federation data directory (a cache that can be deleted while the server is +stopped). If the overlay cannot start, the server log says "public podcast +discovery disabled" and everything else keeps working. The admin +federation status (`/admin/v2/api/federation`) reports `podcast_discovery` +and `podcast_discovery_peers`. ### Podcast feeds and audio diff --git a/docs/development.md b/docs/development.md index fba2ab1..4811641 100644 --- a/docs/development.md +++ b/docs/development.md @@ -204,6 +204,10 @@ node --test tests/player_queue_sources.test.cjs tests/player_podcasts.test.cjs # the migration test creates and drops a database next to it: FURU_DEVICE_SYNC_TEST_DATABASE_URL=postgresql://... \ cargo test postgres_tests -- --ignored +# Sharing, aggregation and a loopback publication from the web node to +# another iroh node (temporary directories): +FURU_DEVICE_SYNC_TEST_DATABASE_URL=postgresql://... \ + cargo test discovery -- --include-ignored FURU_METADATA_FIX_TEST_DATABASE_URL=postgresql://... \ cargo test undo_accepts_playback_archives_written_before_the_typed_queue -- --ignored ``` @@ -212,6 +216,43 @@ FURU_METADATA_FIX_TEST_DATABASE_URL=postgresql://... \ 0.12.x byte for byte; `fixtures/v3_hello.golden.json` is the v3 shape. Rewrite it only for a deliberate change, with `FURUMUSIC_BLESS_GOLDEN=1`. +### Public podcast discovery + +`src/podcasts/discovery.rs` decides what the server node publishes on the +`music_dht::podcast_dht` overlay; `src/federation/podcast_discovery.rs` runs +the overlay on the federation node (ALPN `furumi-fd/podcast-dht/1`, cache +`podcast-dht.sqlite3` in the federation data directory, `serve`, +`maintenance`, the reconciler and a capability probe that calls +`note_peer_capabilities`). The capability manifest advertises `podcast_dht` +only while the overlay runs. + +- The server's node key is the only publisher. Each account's + `AccountShare` is built like the frid integration pattern for SQLite + clients: the merged subscription register (with its aliases) and share + register, and a card from `PodcastCardSpec::from_subscription` with the + 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`). +- `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. +- `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. +- `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 + (otherwise 409 `needs_confirmation` with the warnings, nothing written). + ## Contributing Bug reports, design discussions, and patches are welcome. Before submitting a