Reconcile podcast store and discovery

Cross-reference the SQLite podcast store and the podcast_dht overlay in
PODCASTS.md, ARCHITECTURE.md and the furumi-library README, and test that
the store's merged subscription and share registers build the share state
and cards PodcastDht::sync_shares publishes, including after a feed move
and after unsubscribing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-19 18:32:40 +02:00
1 parent 5a4d418d2b
commit 71e3f1fa0a
4 files changed
+96 -3

No files matched your search

+2 -1
View File
@@ -239,7 +239,8 @@ Public podcast discovery is a third schema-independent Kademlia overlay,
`music_dht::podcast_dht` (ALPN `furumi-fd/podcast-dht/1`, version 1,
capability `podcast_dht`), built like the similarity-routing overlay. A
device publishes a card only for podcasts whose merged registers satisfy
`effective_share`; `sync_shares` reconciles publications declaratively and
`effective_share` (SQLite clients read the merged registers from
`PodcastStore`); `sync_shares` reconciles publications declaratively and
nothing is sent for a podcast the device never published. A card is the
public projection of a podcast (feed URL and channel metadata, no personal
state), signed by the device's iroh identity over a domain-separated
+11 -2
View File
@@ -21,7 +21,7 @@ cards in a separate DHT overlay, `music_dht::podcast_dht`; see
| `music_dht::podcast` | ids, URL canonicalization, no-GUID rule, metadata DTOs and bounds, merge functions, RSS/Atom parser (feature `podcast-feed`) |
| `music_dht::device_sync` | sync operation kinds, snapshot sections, `PlaybackSource`, version gating, Jam redaction |
| `music_dht::podcast_dht` | public podcast cards and tombstones, their signatures, replication, cache and search, privacy warnings for feed URLs |
| Client storage (`furumi_library::podcasts::PodcastStore`, web PostgreSQL) | persistence and migrations implementing the rules below (SQLite reference: see "SQLite reference store") |
| Client storage (`furumi_library::podcasts::PodcastStore`, web PostgreSQL) | persistence and migrations implementing the rules below (SQLite reference: [SQLite reference store](#sqlite-reference-store)) |
| Client runtime | HTTP fetching, conditional requests, scheduling, audio buffering and decoding, UI |
Audio is always fetched from the publisher. It is never imported into the
@@ -716,6 +716,13 @@ Fields are in postcard order. `PodcastDhtKey` is 32 raw bytes.
publishes the same `feed_url` and `id_feed_url`. A feed move to a URL that
looks private therefore asks again; an earlier publication of a held-back
podcast stays as it was.
* SQLite clients build each `PodcastShareState` from
`PodcastStore::subscription` (the merged register with its alias set, which
always contains the origin URL) and `PodcastStore::share`; its `is_shared`
equals `PodcastSummary::shared`. A card for the URL the device now fetches
sets `feed_url` from the catalog and `id_feed_url` to the origin URL. The
store does not persist `privacy_confirmed`; the client keeps that
confirmation. See [SQLite reference store](#sqlite-reference-store).
* `PodcastDht::unpublish(podcast_id)` writes the tombstone. Nothing is ever
sent for a podcast this device never published: no tombstone, no id.
* `PodcastDht::republish` (run by `maintenance`) re-signs active cards and
@@ -928,7 +935,9 @@ must keep the same invariants.
`set_shared`/`unsubscribe` the share register, with
`next_podcast_generation`. No-op actions draw no stamp and emit nothing.
`unsubscribe` emits `subscribed = false` and `shared = false` and keeps
progress, sessions and the catalog.
progress, sessions and the catalog. The store only records the decision;
publishing and revoking the public card is `PodcastDht::sync_shares` (see
[Public discovery](#public-discovery-podcast_dht)).
* Explicit progress actions use `explicit_generation(max(local, carried))`;
checkpoints keep the session generation and are refused (`Superseded`)
once the register holds a greater one, or after the session completed.
+4
View File
@@ -57,6 +57,10 @@ It lives in its own file, conventionally `podcasts.sqlite3`
- **Queries**: `list_podcasts`, `seasons`, `episodes` (season, played-state
and text filters, date or episode-number order), `resume_position_ms`,
`episode_ref` / `episode_track` for queueing, `listen_history`.
- **Public discovery**: the store records share decisions only. Build each
`music_dht::podcast_dht::PodcastShareState` for `PodcastDht::sync_shares`
from `subscription` and `share` (workspace `PODCASTS.md`, section "Public
discovery (podcast_dht)"); the client keeps the user's `privacy_confirmed` decision.
The store is synchronous: methods take `&self` and lock one connection, so
`Arc<PodcastStore>` can be shared; run calls on a blocking pool.
@@ -2242,3 +2242,82 @@ fn concurrent_fetch_state_writers_lose_no_update() {
assert_eq!(state.consecutive_failures as usize, THREADS * FAILURES);
assert_eq!(state.cover_path.as_deref(), Some("/covers/c.jpg"));
}
// ---------------------------------------------------------------------------
// Public discovery (`music_dht::podcast_dht`)
/// The share state `PodcastDht::sync_shares` takes, built from the store the
/// way clients do it.
fn discovery_state(
store: &PodcastStore,
podcast_id: &PodcastId,
) -> music_dht::podcast_dht::PodcastShareState {
music_dht::podcast_dht::PodcastShareState {
subscription: store.subscription(podcast_id).unwrap().unwrap(),
share: store.share(podcast_id).unwrap(),
card: None,
privacy_confirmed: false,
}
}
#[test]
fn store_registers_drive_discovery_publication() {
let store = PodcastStore::open_in_memory().unwrap();
let mut stamps = TestStamps::new("device-a", 1_000);
let podcast_id = store
.subscribe(&mut stamps, &meta(FEED, "Show"))
.unwrap()
.podcast_id;
// Subscribed but private: nothing to publish.
let state = discovery_state(&store, &podcast_id);
assert!(!state.is_shared());
assert!(!store.podcast(&podcast_id).unwrap().unwrap().shared);
store.set_shared(&mut stamps, &podcast_id, true).unwrap();
let state = discovery_state(&store, &podcast_id);
assert!(state.is_shared());
assert!(store.podcast(&podcast_id).unwrap().unwrap().shared);
let card = state.card_spec().unwrap();
assert_eq!(card.podcast_id, podcast_id);
assert_eq!(card.feed_url, url(FEED));
assert_eq!(card.id_feed_url, None);
assert_eq!(card.title, "Show");
assert!(card.privacy_warnings().is_empty());
// After a permanent move the register's alias set still holds the origin
// URL, so the card stays bound to the podcast id.
let items = [Item::new(
Some("g1"),
"One",
"https://cdn.example.test/1.mp3",
)];
let moved = url("https://new.example.test/feed.xml");
let feed = parse(&rss("Show", None, &items), &moved);
refresh(&store, &mut stamps, &podcast_id, &feed, &moved, true);
let state = discovery_state(&store, &podcast_id);
assert!(state.subscription.feed_urls().contains(&moved));
let card = state.card_spec().unwrap();
assert_eq!(card.podcast_id, podcast_id);
// A card for the URL this device now fetches names the origin URL.
let summary = store.podcast(&podcast_id).unwrap().unwrap();
assert_eq!(summary.meta.feed_url, moved);
let fetched = music_dht::podcast_dht::PodcastShareState {
card: Some(music_dht::podcast_dht::PodcastCardSpec {
feed_url: summary.meta.feed_url.clone(),
id_feed_url: Some(url(FEED)),
..card
}),
..state
};
let card = fetched.card_spec().unwrap();
assert_eq!(card.feed_url, moved);
assert_eq!(card.id_feed_url, Some(url(FEED)));
card.validate().unwrap();
// Unsubscribing revokes the share decision: the card must be unpublished.
store.unsubscribe(&mut stamps, &podcast_id).unwrap();
let state = discovery_state(&store, &podcast_id);
assert!(!state.is_shared());
assert!(!store.podcast(&podcast_id).unwrap().unwrap().shared);
}