Document public podcast discovery in the web server

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:51 +02:00
1 parent 675a63a465
commit 27fc2c5354
3 files changed
+118 -5

No files matched your search

+24
View File
@@ -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
+53 -5
View File
@@ -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
+41
View File
@@ -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