diff --git a/AGENTS.md b/AGENTS.md index 10f5084..f5f7357 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,7 +69,10 @@ update it only when dependencies change. `podcasts::publication` (`PodcastDht::sync_shares` over the merged registers): never publish a podcast directly, never log feed URLs or ids of podcasts that are not shared, never put progress, history, counters or - device names into a card. Public cards found by search are publisher claims: + device names into a card. A local share-off or unsubscribe asks for an + immediate pass (`Reconciler::revoke_now`), which quitting waits for, and + privacy confirmations change only through `publication::set_shared` / + `ShareConfirmations` (bound to the share decision, never synced). Public cards found by search are publisher claims: subscribe and preview only through `podcasts::discovery`, which uses the card's origin URL (`PodcastSearchHit::feed_url`), never a claimed URL, and never stores card metadata. Queue items are identified by `state::track_key` diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index c2b83a5..f1a11f9 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -406,8 +406,9 @@ The TUI owns what the contract leaves to clients: `podcast_dht` in its own manifest only while the overlay runs. A cache that cannot be opened is logged and only turns discovery off. What this device publishes is decided by `podcasts::publication`: after local share - and unsubscribe actions, received podcast operations, feed refreshes, - every overlay (re)start and every 5 minutes it builds one + and unsubscribe actions (at once: `Reconciler::revoke_now`), received + podcast operations and feed refreshes (debounced 1 s), every overlay + (re)start and every 5 minutes it builds one `PodcastShareState` per subscription (merged registers, a card from the catalog for shared podcasts only, the local privacy confirmation) and calls the declarative `PodcastDht::sync_shares`, which publishes what is @@ -417,14 +418,24 @@ The TUI owns what the contract leaves to clients: republish. Publication runs from each device's own identity. Privacy confirmations of feed URLs that look private are device-local (`podcast-share-confirmations.json`, mode 0600) and bound to the exact - URLs. Without a readable podcast store this device revokes all its own - cards. Logs carry counts only. -- **Finding and subscribing.** `Federation::search` runs - `PodcastDht::search` next to the music DHT search and takes the podcast - entries of `merge_search_results` (exact titles first) as - `podcasts::discovery::PodcastHit`s; the music sections keep their own - aggregation and ranking, so music results are unchanged. Off the UI - thread each hit's origin URL is resolved with + URLs and to the share decision (the share register's operation): a newer + decision on any device drops them. Cards leave out artwork and web links + that look private, and both for a private-looking feed. Without a + readable podcast store this device revokes all its own cards. The report + of each pass lists the private podcasts whose own card is still live + (`unrevoked`: pending, failed or federation off) for the side panel; the + overlay peer count is refreshed every 10 s between passes. Before the + node stops on quit, `Reconciler::flush` waits up to 4 s for a revocation + requested just before. Logs carry counts only. +- **Finding and subscribing.** `Federation::search_podcasts` + (`podcasts::discovery::search`) runs `PodcastDht::search` as its own task, + bounded at 15 s including the overlay's bootstrap, apart from the music + search (`Federation::search`, unchanged), and delivers + `AppEvent::FedPodcastsLoaded` for the same search sequence, so music + results never wait for the overlay. The hits keep the podcast entries of + `merge_search_results` (exact titles first) as + `podcasts::discovery::PodcastHit`s. Off the UI thread each hit's origin + URL is resolved with `PodcastStore::resolve_podcast_id`, and the "subscribed" mark compares that id and the card's id with the subscribed podcasts, so a feed alias counts. A card is a publisher's claim: only `PodcastSearchHit::feed_url` @@ -433,7 +444,11 @@ The TUI owns what the contract leaves to clients: «Подписаться» (`discovery::subscribe_from_hit` → `refresh::subscribe_url`), which refuses a hit whose id does not match its URL and stores only what the feed says. Claimed moved-feed URLs are displayed, never fetched or - recorded as aliases. The new subscription is private. + recorded as aliases. The new subscription is private. Subscribing to an + address whose feed announces (`itunes:new-feed-url`) a newer one this + device already follows reports that subscription instead of adding a + second one, and the preview (`discovery::preview_for`) resolves the + address the feed moved to, so the card reads «Уже подписан» then. - **Progress.** `podcasts::progress` runs one writer thread so every progress write of this device is ordered. The app tick follows the position and actual listening time and sends: an explicit start (or diff --git a/CHANGELOG.md b/CHANGELOG.md index d0b4379..b37ee68 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,18 +19,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 published only after a confirmation on that device. The list and side panel show whether a podcast is shared and whether this device publishes it. +- Turning sharing off or unsubscribing revokes this device's card at once, + and quitting waits up to 4 s for that; the side panel says when a + private podcast's card is not revoked yet (pending, failed or federation + off). A privacy confirmation covers one share decision: turning sharing + off (or on again after that) on any trusted device asks again. Cards + leave out artwork and web links that look like they carry an access key, + and both for a feed whose URL looks private. - Search (`/`, with the federation running) also finds public podcast cards. They are listed after the music results under "Podcasts · public cards" with a `[podcast]` marker, the number of publishing devices, and "✓ subscribed" - when this device is subscribed (also through a feed alias). Local-only - search is unchanged. + when this device is subscribed (also through a feed alias). The podcast + search runs apart from the federated music search (bounded at 15 s), so + music results never wait for it; local-only search is unchanged. - Enter on a podcast hit opens its card: title, author, categories, description, episode count, newest episode, publishing devices, feed URL and unverified moved-feed claims. `e` reads the seasons and episodes from the feed without subscribing. «Подписаться» (Enter) subscribes privately with the card's origin feed URL, so the podcast id is the card's, and reads everything from the feed itself; «Уже подписан» opens the podcast - in the Podcasts tab instead. + in the Podcasts tab instead, also when this device follows the feed under + the newer address it moved to (known once the feed was read), and + subscribing to such an older address adds no second subscription. ### Changed diff --git a/README.md b/README.md index d247c3d..132115d 100644 --- a/README.md +++ b/README.md @@ -292,22 +292,34 @@ Sharing a podcast (public discovery): podcast under its own device key: the feed URL, title, author, description, artwork and web links, the number of episodes and the date of the newest one. The card never contains your progress, history, play - counts, device names or anything from podcasts you did not share. + counts, device names or anything from podcasts you did not share. Artwork + and web links that look like they carry an access key are left out, and + so are both for a feed whose own URL looks private. - If the feed URL looks private (a token, key or signature in its query, a member-feed host such as Patreon, a long random-looking part), Furumi asks first and lists why (in Russian). Anyone who finds the card can read the feed at that URL. The confirmation is stored only on this device (`podcast-share-confirmations.json` next to `podcasts.sqlite3`) and covers - exactly the URLs shown: another device of yours asks again before it - publishes, and so does this one if the feed moves. Until then the side - panel says the publication is held back; press `Shift+F` there to - confirm (or `x` in the dialog to stop sharing). + exactly the URLs shown and this one decision to share: another device of + yours asks again before it publishes, and so does this one if the feed + moves or if sharing is turned off (or turned on again after that) on any + of your devices. Until then the side panel says the publication is held + back; press `Shift+F` there to confirm (or `x` in the dialog to stop + sharing). - `Shift+F` on a shared podcast, or unsubscribing, makes it private again on - every device: each device replaces its card with a signed removal record. - Removal spreads with the usual delay of the network: a copy that missed - it can still be found until it expires (at most 12 hours). Removing your - card never touches other people's subscriptions. An older device that - comes back with the earlier "share" decision does not publish it again. + every device in your group: each device replaces its card with a signed + removal record. This device sends its removal right away, and quitting + waits for it (up to 4 seconds). While the removal is not sent yet (or + could not be sent, or the federation is off), the side panel says the + public card is not revoked yet instead of just "private". With the + federation off, the removal is sent the next time it runs; until then, + and for a copy that missed the removal, the card can still be found until + it expires (at most 12 hours). Removing your card never touches other + people's subscriptions. An older device that comes back with the earlier + "share" decision does not publish it again. +- A device that left your device group, or was removed from it, no longer + receives your share decisions: it keeps publishing the podcasts it shares + until you turn sharing off (or unsubscribe) on that device itself. - The card is signed with this device's federation key, which is also the key of its public music library, so a shared podcast can be linked to that library and to the device's network address. @@ -322,9 +334,14 @@ Finding public podcasts: with the number of devices that publish the card (devices, not subscribers; anyone can create devices, so it is not a sign of trust) or "✓ subscribed" when this device already follows the podcast, also when - you subscribed under an older or newer address of the same feed. Your - query words go to the discovery peers, as they do for music search. With - the federation off, search stays local and shows no podcasts. + you subscribed under an older address of the same feed that moved to the + card's address. When you follow the feed under a newer address than the + card's, the list cannot tell yet; the card can once its episodes are read + (`e`), and «Подписаться» never adds a second subscription for it. Your + query words go to the discovery peers, as they do for music search. The + podcast search runs apart from the music search (music results never wait + for it) and gives up after 15 seconds. With the federation off, search + stays local and shows no podcasts. - Enter opens the card (in Russian): what its publishers claim (title, author, categories, description, number of episodes and date of the newest one), the feed URL, and addresses some publishers claim the feed @@ -338,7 +355,9 @@ Finding public podcasts: online, and nothing from the card is kept. The new subscription is private like any other: it is not shared until you press `Shift+F`, and your progress is your own. «Уже подписан» means this device is already - subscribed; Enter then opens the podcast in the Podcasts tab. + subscribed (under the card's address, an older one, or — once the feed + was read — the newer address the feed moved to); Enter then opens the + podcast in the Podcasts tab. Podcast data lives in `podcasts.sqlite3` in the platform data directory (the same file the earlier podcast test build used; it is upgraded in place). If