forked from Furumi/furumi-web
Document public podcast discovery in the web server
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
675a63a465
commit
27fc2c5354
3 files changed
+118
-5
No files matched your search
@@ -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
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user