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

+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