From 6d225531a5c35743adfbf6541c46c01bdd374d52 Mon Sep 17 00:00:00 2001 From: Sanapach Date: Thu, 19 Nov 2026 23:08:47 +0200 Subject: [PATCH] Document sharing podcasts in the federation Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 5 ++++- ARCHITECTURE.md | 27 +++++++++++++++++++++++++-- CHANGELOG.md | 9 ++++++++- README.md | 38 ++++++++++++++++++++++++++++++++++++-- 4 files changed, 73 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8cb1fe3..8df1764 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -65,7 +65,10 @@ update it only when dependencies change. stream reader (HTTP Range, bounded buffer) and the ordered progress writer; podcast identity, merge rules and the SQLite store come from FRID (`music_dht::podcast`, `furumi_library::podcasts`) and must not be - re-derived here. Queue items are identified by `state::track_key` / + re-derived here. Public podcast cards are published only through + `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. Queue items are identified by `state::track_key` / `TrackItem::key`, never by numeric id (every episode has the same sentinel id); music-only code must skip `TrackItem::is_podcast()` items. - `src/devices.rs` owns trusted-device replication, membership, and playback diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 6191f0c..a58e6eb 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -398,6 +398,27 @@ The TUI owns what the contract leaves to clients: one within the completion window, completes the episode and moves the queue on; otherwise the last seen position is saved and playback stops on the episode (`playback::played_to_the_end`). +- **Public discovery.** The federation node runs FRID's signed podcast + overlay (`music_dht::podcast_dht`, ALPN `furumi-fd/podcast-dht/1`, cache + `federation/podcast-dht.sqlite3`) next to the similarity overlay: it + serves the overlay, bootstraps, republishes and expires records, hands + every peer capability manifest to `note_peer_capabilities`, and advertises + `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 + `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 + shared and tombstones every other own card. The share decision is the + synced `podcast_share_set` register, so share-off or unsubscribe on any + trusted device revokes every device's card and a stale device cannot + 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. - **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 @@ -541,6 +562,8 @@ Furumi stores different kinds of state according to their lifetime: | --- | --- | --- | | Library, playlists, likes, history | SQLite | Durable local source of truth | | Podcast subscriptions, episodes, progress | SQLite (`podcasts.sqlite3`, FRID store) | Durable personal state (synced with trusted devices) and a refreshable episode catalog | +| Podcast share confirmations | JSON next to `podcasts.sqlite3` | Device-local consent to publish feed URLs that look private | +| Public podcast cards (own and replicas) | SQLite (`federation/podcast-dht.sqlite3`) | Discovery overlay cache; replaceable | | Device operation log and replicas | SQLite | Offline synchronization | | Versioned track embeddings | SQLite | Durable, locally rebuildable similarity data | | Federation catalog cache | SQLite/cache | Faster network browsing | @@ -580,8 +603,8 @@ The source tree follows the architectural responsibilities: - `federation/` owns DHT-facing search, peer catalogs, and audio exchange; - `podcasts/` owns feed HTTP (conditional requests, redirects, limits), refresh scheduling policy, the episode stream reader and the progress - writer; the podcast model, identity, merge rules and SQLite store come - from FRID; + writer, and the publication of shared podcasts; the podcast model, + identity, merge rules, SQLite store and discovery overlay come from FRID; - `devices.rs` owns trusted-device replication and playback coordination; - `app/` owns state transitions and runtime orchestration; - `ui/` renders the TUI; diff --git a/CHANGELOG.md b/CHANGELOG.md index 2b7a022..d2e5772 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -45,7 +45,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 is cancelled at the next start or stop; pause pressed while an episode connects is kept; seeks that do not move the audio are not saved. - Podcast key bindings in the `podcasts` context: `o`, `/`, `Shift+R`, - `Ctrl+R`, `Shift+S`, `f`, `m`, `Shift+U`, `b`. + `Ctrl+R`, `Shift+S`, `f`, `m`, `Shift+U`, `b`, `Shift+F`. +- Sharing a podcast in the federation (`Shift+F`, off by default): the + synced share decision makes each device publish a signed public card of + the podcast in the FRID discovery overlay (`podcast_dht`, advertised in + the capability manifest); share-off and unsubscribe revoke it with a + tombstone. Feed URLs that look private are 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. - An optional top-level `version` in `keymap.toml`; the current format is `version = 2`, and a `podcasts` binding context. diff --git a/README.md b/README.md index 5d52dde..fc0714d 100644 --- a/README.md +++ b/README.md @@ -208,6 +208,10 @@ never imported into the music library or offered to other peers. - `Shift+U` (or `Shift+D`) unsubscribes after a confirmation. Listening progress and history are kept, so subscribing again continues where you left off. +- `Shift+F` shares the selected (or opened) podcast in the federation, or + makes it private again. The list marks shared podcasts with `shared`, and + the side panel says whether this device publishes the card (see + "Sharing a podcast" below). Episodes play in the same queue as music: @@ -251,8 +255,7 @@ Podcasts and your connected devices: history are personal. They are synchronized only between your trusted devices (Connected Devices), never published to the federation: no DHT record, public catalog or search result contains them. Publishing a - podcast for discovery is a separate, explicit choice that this version - does not offer yet. + podcast for discovery is a separate, explicit choice (`Shift+F`, below). - **Synchronized between trusted devices.** A podcast you subscribe to on one device appears on the others without typing its URL again; each device then checks the feed itself. Unsubscribing, "played", the saved @@ -281,6 +284,37 @@ Podcasts and your connected devices: or address), cannot add episodes to the host's queue and cannot seek in a private item. They can still reorder the queue and skip. +Sharing a podcast (public discovery): + +- `Shift+F` turns "share in the federation" on for one podcast. The choice is + synchronized to your trusted devices like a subscription; each of your + devices that runs the federation then publishes a small public card of the + 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. +- 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). +- `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. +- 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. +- Publishing needs the federation to be running; the side panel shows + "not published" with the reason otherwise. Search and subscribing from a + public card come in a later step of this feature. + 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 that file was written by a newer Furumi or is not a podcast database, the tab