diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index c18823f..06dbf21 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -123,6 +123,14 @@ The DHT is the distributed index. Nodes publish compact searchable descriptions of their local library and query the network without contacting a central search service. +Opening a local artist or release card in a network-enabled library view +enriches it asynchronously. DHT matches identify likely catalog owners, while +a bounded set of known peers can also answer directly when the index is +incomplete. Card results are replaceable snapshots: reopening a card or +periodic maintenance retries discovery, with at most one request per card in +flight. A failed refresh keeps the last usable snapshot, and never prevents +browsing the local tracks. + Similarity discovery uses a separate schema-independent DHT overlay. A node derives a deterministic 256-bit routing signature from every local embedding, groups them into fixed two-level LSH buckets, and publishes compact summaries diff --git a/Cargo.toml b/Cargo.toml index aaae58a..0c76128 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "furumi_tui" -version = "0.3.4" +version = "0.3.5" edition = "2024" rust-version = "1.97" description = "A federated P2P player for personal music libraries" diff --git a/src/app/enrichment.rs b/src/app/enrichment.rs new file mode 100644 index 0000000..b85556a --- /dev/null +++ b/src/app/enrichment.rs @@ -0,0 +1,137 @@ +//! Scheduling for local cards enriched by replaceable federation data. + +use std::collections::HashMap; +use std::time::{Duration, Instant}; + +use super::state::{AppState, GlobalView, Loadable, Tab}; + +const REFRESH_INTERVAL: Duration = Duration::from_secs(30); + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub(super) enum Card { + Artist(i64), + Release(i64), +} + +#[derive(Debug, Default)] +pub(super) struct RefreshState { + visible: Option, + /// None means a request is in flight; Some is its completion time. + requests: HashMap>, +} + +impl RefreshState { + fn begin(&mut self, visible: Option, now: Instant) -> bool { + let reopened = self.visible != visible; + self.visible = visible; + let Some(card) = visible else { return false }; + match self.requests.get(&card) { + Some(None) => return false, + Some(Some(completed)) + if !reopened && now.duration_since(*completed) < REFRESH_INTERVAL => + { + return false; + } + _ => {} + } + self.requests.insert(card, None); + true + } + + pub(super) fn complete(&mut self, card: Card, now: Instant) { + self.requests.insert(card, Some(now)); + } +} + +#[derive(Debug, PartialEq, Eq)] +pub(super) enum Request { + Artist { + id: i64, + name: String, + }, + Release { + id: i64, + title: String, + artists: Vec, + }, +} + +/// Called on navigation and maintenance ticks. A cached success or failure +/// must not suppress discovery for the rest of the session. +pub(super) fn prepare(state: &mut AppState, now: Instant) -> Option { + let visible = if state.federation.settings.enabled + && state.global.filters.source_mode.includes_network() + && state.active_tab == Tab::Global + { + match state.global.stack.last() { + Some(GlobalView::Artist { id, .. }) => Some(Card::Artist(*id)), + Some(GlobalView::Release { id, .. }) => Some(Card::Release(*id)), + _ => None, + } + } else { + None + }; + let request = match visible { + Some(Card::Artist(id)) => match state.artist_views.get(&id) { + Some(Loadable::Ready(detail)) => Some(Request::Artist { + id, + name: detail.name.clone(), + }), + _ => None, + }, + Some(Card::Release(id)) => match state.release_views.get(&id) { + Some(Loadable::Ready(detail)) => { + let mut artists = Vec::new(); + for artist in &detail.artists { + if !artists.iter().any(|name: &String| { + music_dht::normalize_name(name) == music_dht::normalize_name(&artist.name) + }) { + artists.push(artist.name.clone()); + } + } + (!artists.is_empty()).then(|| Request::Release { + id, + title: detail.title.clone(), + artists, + }) + } + _ => None, + }, + None => None, + }; + if !state + .card_enrichment + .begin(visible.filter(|_| request.is_some()), now) + { + return None; + } + match &request { + Some(Request::Artist { id, .. }) => mark_loading(&mut state.artist_fed_views, *id), + Some(Request::Release { id, .. }) => mark_loading(&mut state.release_fed_views, *id), + None => {} + } + request +} + +fn mark_loading(views: &mut HashMap>, id: i64) { + if !matches!(views.get(&id), Some(Loadable::Ready(_))) { + views.insert(id, Loadable::Loading); + } +} + +/// Keep the last usable snapshot if a refresh fails while peers are offline. +pub(super) fn store_result( + views: &mut HashMap>, + id: i64, + result: Result, +) { + match result { + Ok(value) => { + views.insert(id, Loadable::Ready(value)); + } + Err(message) if !matches!(views.get(&id), Some(Loadable::Ready(_))) => { + views.insert(id, Loadable::Failed(message)); + } + Err(_) => {} + } +} diff --git a/src/app/mod.rs b/src/app/mod.rs index ba7ee52..9c4517a 100644 --- a/src/app/mod.rs +++ b/src/app/mod.rs @@ -1,6 +1,7 @@ pub mod action; mod cmdline; pub mod command; +mod enrichment; pub mod event; pub mod input; pub(crate) mod popup; @@ -310,54 +311,16 @@ fn spawn_release_federation_enrichment( }); } -fn maybe_enrich_open_artist(state: &mut AppState, runtime: &Runtime) { - if !state.federation.settings.enabled || state.active_tab != state::Tab::Global { - return; - } - let Some(state::GlobalView::Artist { id, .. }) = state.global.stack.last().copied() else { - return; - }; - if state.artist_fed_views.contains_key(&id) { - return; - } - let Some(state::Loadable::Ready(detail)) = state.artist_views.get(&id) else { - return; - }; - let name = detail.name.clone(); - state.artist_fed_views.insert(id, state::Loadable::Loading); - spawn_artist_federation_enrichment(runtime, id, name); -} - -fn maybe_enrich_open_release(state: &mut AppState, runtime: &Runtime) { - if !state.federation.settings.enabled - || !state.global.filters.source_mode.includes_network() - || state.active_tab != state::Tab::Global - { - return; - } - let Some(state::GlobalView::Release { id, .. }) = state.global.stack.last().copied() else { - return; - }; - if state.release_fed_views.contains_key(&id) { - return; - } - let Some(state::Loadable::Ready(detail)) = state.release_views.get(&id) else { - return; - }; - let mut artists = Vec::new(); - for artist in &detail.artists { - if !artists.iter().any(|name: &String| { - music_dht::normalize_name(name) == music_dht::normalize_name(&artist.name) - }) { - artists.push(artist.name.clone()); +fn maybe_enrich_open_card(state: &mut AppState, runtime: &Runtime) { + match enrichment::prepare(state, std::time::Instant::now()) { + Some(enrichment::Request::Artist { id, name }) => { + spawn_artist_federation_enrichment(runtime, id, name); } + Some(enrichment::Request::Release { id, title, artists }) => { + spawn_release_federation_enrichment(runtime, id, title, artists); + } + None => {} } - if artists.is_empty() { - return; - } - let title = detail.title.clone(); - state.release_fed_views.insert(id, state::Loadable::Loading); - spawn_release_federation_enrichment(runtime, id, title, artists); } fn spawn_content_id_backfill(runtime: &Runtime) { @@ -1195,8 +1158,7 @@ fn maintenance(state: &mut AppState, runtime: &mut Runtime) { maybe_refresh_network_library(state, runtime); maybe_fetch_network_artist_images(state, runtime); - maybe_enrich_open_artist(state, runtime); - maybe_enrich_open_release(state, runtime); + maybe_enrich_open_card(state, runtime); // Liked ids load once per session — markers are shown everywhere. if !state.likes_loaded { @@ -3804,26 +3766,27 @@ fn handle_app_event(state: &mut AppState, runtime: &mut Runtime, event: AppEvent } AppEvent::ArtistFederationLoaded { id, name, result } => { let cursor_anchor = state::artist_cursor_anchor(state, id); - let entry = match result { - Ok(card) => state::Loadable::Ready(card), - Err(message) => { - tracing::debug!(artist = id, %name, %message, "artist federation enrichment failed"); - state::Loadable::Failed(message) - } - }; - state.artist_fed_views.insert(id, entry); + state + .card_enrichment + .complete(enrichment::Card::Artist(id), std::time::Instant::now()); + if let Err(message) = &result { + tracing::debug!(artist = id, %name, %message, "artist federation enrichment failed"); + } + enrichment::store_result(&mut state.artist_fed_views, id, result); state::restore_artist_cursor_anchor(state, id, cursor_anchor); } AppEvent::ReleaseFederationLoaded { id, result } => { - let entry = match result { - Ok(Some(release)) => state::Loadable::Ready(release), - Ok(None) => state::Loadable::Ready(crate::federation::FedRelease::default()), - Err(message) => { - tracing::debug!(release = id, %message, "release federation enrichment failed"); - state::Loadable::Failed(message) - } - }; - state.release_fed_views.insert(id, entry); + state + .card_enrichment + .complete(enrichment::Card::Release(id), std::time::Instant::now()); + if let Err(message) = &result { + tracing::debug!(release = id, %message, "release federation enrichment failed"); + } + enrichment::store_result( + &mut state.release_fed_views, + id, + result.map(Option::unwrap_or_default), + ); } AppEvent::NetworkArtistCacheUpdated { source_id, count } => { tracing::debug!(source = %source_id, count, "network artist cache updated"); @@ -3937,7 +3900,7 @@ fn handle_app_event(state: &mut AppState, runtime: &mut Runtime, event: AppEvent } }; state.artist_views.insert(id, entry); - maybe_enrich_open_artist(state, runtime); + maybe_enrich_open_card(state, runtime); } AppEvent::ReleaseViewLoaded { id, result } => { let entry = match result { @@ -3948,7 +3911,7 @@ fn handle_app_event(state: &mut AppState, runtime: &mut Runtime, event: AppEvent } }; state.release_views.insert(id, entry); - maybe_enrich_open_release(state, runtime); + maybe_enrich_open_card(state, runtime); // A Shift-J jump was waiting for this release: focus its track. if let Some((release_id, track_id)) = state.pending_release_focus && release_id == id diff --git a/src/app/state.rs b/src/app/state.rs index bc8d66b..0867955 100644 --- a/src/app/state.rs +++ b/src/app/state.rs @@ -1680,6 +1680,7 @@ pub struct AppState { pub release_views: HashMap>, /// Federated tracks that enrich an already-open local release view. pub release_fed_views: HashMap>, + pub(super) card_enrichment: super::enrichment::RefreshState, pub playlists: PlaylistsTab, pub playlist_views: HashMap>, /// Liked local-library content ids, for the ♥ markers everywhere tracks are shown. diff --git a/src/app/update_tests.rs b/src/app/update_tests.rs index 9a0ee8a..5df32dd 100644 --- a/src/app/update_tests.rs +++ b/src/app/update_tests.rs @@ -1073,3 +1073,211 @@ fn view_toggle() { update(&mut state, Action::ToggleViewMode); assert_eq!(state.global.view, ViewMode::Tiles); } + +fn enrichment_state(release: bool) -> AppState { + use crate::library::models::{ArtistRef, ReleaseDetail}; + let mut state = AppState::default(); + state.federation.settings.enabled = true; + state.global.filters.source_mode = crate::config::settings::LibrarySourceMode::Global; + state.artist_views.insert( + 1, + Loadable::Ready(ArtistDetail { + id: 1, + name: "Artist".into(), + image_path: None, + total_track_count: 1, + total_play_count: 0, + top_tracks: vec![test_track(1)], + featured_tracks: vec![], + releases: vec![], + }), + ); + state.release_views.insert( + 1, + Loadable::Ready(ReleaseDetail { + id: 1, + title: "Release".into(), + release_type: "album".into(), + year: None, + cover_path: None, + artists: vec![ArtistRef { + id: 1, + name: "Artist".into(), + }], + tracks: vec![test_track(1)], + }), + ); + state.global.stack.push(if release { + GlobalView::Release { id: 1, cursor: 0 } + } else { + GlobalView::Artist { id: 1, cursor: 0 } + }); + state +} + +#[test] +fn card_enrichment_retries_startup_failure_without_reopening() { + use crate::app::enrichment::{self, Card, Request}; + use std::time::{Duration, Instant}; + for release in [false, true] { + let mut state = enrichment_state(release); + let now = Instant::now(); + let request = enrichment::prepare(&mut state, now).unwrap(); + let card = match request { + Request::Artist { id: 1, ref name } if name == "Artist" => Card::Artist(1), + Request::Release { + id: 1, + ref title, + ref artists, + } if title == "Release" && artists == &["Artist"] => Card::Release(1), + _ => panic!("wrong enrichment request: {request:?}"), + }; + // Slow requests are never duplicated, even after the refresh interval. + assert!(enrichment::prepare(&mut state, now + Duration::from_secs(60)).is_none()); + let completed = now + Duration::from_secs(60); + state.card_enrichment.complete(card, completed); + if release { + enrichment::store_result( + &mut state.release_fed_views, + 1, + Err("federation is not running".into()), + ); + } else { + enrichment::store_result( + &mut state.artist_fed_views, + 1, + Err("federation is not running".into()), + ); + } + assert!(enrichment::prepare(&mut state, completed + Duration::from_secs(1)).is_none()); + assert_eq!( + enrichment::prepare(&mut state, completed + Duration::from_secs(30)), + Some(request) + ); + assert!(matches!( + state.artist_views.get(&1), + Some(Loadable::Ready(_)) + )); + assert!(matches!( + state.release_views.get(&1), + Some(Loadable::Ready(_)) + )); + } +} + +#[test] +fn card_enrichment_reopens_cached_cards_and_keeps_success_during_failed_refresh() { + use crate::app::enrichment::{self, Card}; + use std::time::{Duration, Instant}; + for release in [false, true] { + let mut state = enrichment_state(release); + let now = Instant::now(); + let request = enrichment::prepare(&mut state, now).unwrap(); + state.card_enrichment.complete( + if release { + Card::Release(1) + } else { + Card::Artist(1) + }, + now, + ); + if release { + enrichment::store_result( + &mut state.release_fed_views, + 1, + Ok(crate::federation::FedRelease { + title: "Release".into(), + ..Default::default() + }), + ); + } else { + enrichment::store_result( + &mut state.artist_fed_views, + 1, + Ok(crate::federation::FedArtistCard { + name: "Artist".into(), + ..Default::default() + }), + ); + } + // Successful but local-only/empty snapshots must also be refreshed. + assert!(enrichment::prepare(&mut state, now).is_none()); + let view = state.global.stack.pop().unwrap(); + assert!(enrichment::prepare(&mut state, now).is_none()); + state.global.stack.push(view); + assert_eq!( + enrichment::prepare(&mut state, now + Duration::from_secs(1)), + Some(request) + ); + if release { + assert!(matches!( + state.release_fed_views.get(&1), + Some(Loadable::Ready(_)) + )); + enrichment::store_result(&mut state.release_fed_views, 1, Err("offline".into())); + assert!( + matches!(state.release_fed_views.get(&1), Some(Loadable::Ready(card)) if card.title == "Release") + ); + } else { + assert!(matches!( + state.artist_fed_views.get(&1), + Some(Loadable::Ready(_)) + )); + enrichment::store_result(&mut state.artist_fed_views, 1, Err("offline".into())); + assert!( + matches!(state.artist_fed_views.get(&1), Some(Loadable::Ready(card)) if card.name == "Artist") + ); + } + } +} + +#[test] +fn card_enrichment_respects_network_mode_and_deduplicates_navigation() { + use crate::app::enrichment; + use crate::config::settings::LibrarySourceMode; + use std::time::Instant; + for release in [false, true] { + let mut state = enrichment_state(release); + let now = Instant::now(); + state.federation.settings.enabled = false; + assert!(enrichment::prepare(&mut state, now).is_none()); + state.federation.settings.enabled = true; + state.global.filters.source_mode = LibrarySourceMode::Local; + assert!(enrichment::prepare(&mut state, now).is_none()); + state.global.filters.source_mode = LibrarySourceMode::Global; + assert!(enrichment::prepare(&mut state, now).is_some()); + state.active_tab = Tab::Queue; + assert!(enrichment::prepare(&mut state, now).is_none()); + state.active_tab = Tab::Global; + assert!(enrichment::prepare(&mut state, now).is_none()); + } +} + +#[test] +fn card_enrichment_refreshes_local_only_success_while_still_open() { + use crate::app::enrichment::{self, Card}; + use std::time::{Duration, Instant}; + for release in [false, true] { + let mut state = enrichment_state(release); + let now = Instant::now(); + let request = enrichment::prepare(&mut state, now).unwrap(); + state.card_enrichment.complete( + if release { + Card::Release(1) + } else { + Card::Artist(1) + }, + now, + ); + if release { + enrichment::store_result(&mut state.release_fed_views, 1, Ok(Default::default())); + } else { + enrichment::store_result(&mut state.artist_fed_views, 1, Ok(Default::default())); + } + assert!(enrichment::prepare(&mut state, now + Duration::from_secs(29)).is_none()); + assert_eq!( + enrichment::prepare(&mut state, now + Duration::from_secs(30)), + Some(request) + ); + } +} diff --git a/src/federation/mod.rs b/src/federation/mod.rs index 4a8e189..5ac9604 100644 --- a/src/federation/mod.rs +++ b/src/federation/mod.rs @@ -1486,31 +1486,38 @@ impl Federation { let own = service.endpoint_id(); let own_hex = own.to_string(); let normalized = music_dht::normalize_name(name); - let outcome = service - .search_network(name) - .await - .map_err(|err| anyhow::anyhow!("federated search failed: {err}"))?; + // A partial/unavailable DHT index must not prevent direct catalog + // requests to peers we already know. Keep discovery bounded so an + // open card cannot remain in Loading indefinitely. + let network_results = match tokio::time::timeout( + Duration::from_secs(10), + service.search_network(name), + ) + .await + { + Ok(Ok(outcome)) => outcome.network_results, + Ok(Err(error)) => { + tracing::debug!(artist = %name, %error, "artist discovery failed; trying known peers"); + Vec::new() + } + Err(_) => { + tracing::debug!(artist = %name, "artist discovery timed out; trying known peers"); + Vec::new() + } + }; let cached_metadata = self.cached_metadata_snapshot(); let has_cached_artist = cached_metadata .iter() .any(|cached| cached_has_artist(cached, &normalized)); - let owners: std::collections::HashSet = outcome - .network_results - .iter() - .filter(|item| { - (item.kind == ItemKind::Artist && item.normalized_name == normalized) - || item - .artist_names - .iter() - .any(|artist| music_dht::normalize_name(artist) == normalized) - || item - .featured_artist_names - .iter() - .any(|artist| music_dht::normalize_name(artist) == normalized) - }) - .map(|item| item.owner) - .filter(|owner| *owner != own) - .collect(); + let owners = artist_catalog_owners( + &network_results, + &normalized, + own, + service + .connected_peers() + .into_iter() + .chain(service.known_peers().into_iter().map(|peer| peer.peer_id)), + ); let local_library = Arc::clone(&self.library); let local_name = name.to_string(); @@ -1565,7 +1572,7 @@ impl Federation { } } let mut card = catalog::merge_catalogs(name, catalogs); - add_dht_appearance_hits(&mut card, &outcome.network_results, &normalized, name); + add_dht_appearance_hits(&mut card, &network_results, &normalized, name); add_cached_appearance_hits(&mut card, &cached_metadata, &normalized, name); anyhow::ensure!( !card.releases.is_empty() || !card.appears_on.is_empty(), @@ -2406,6 +2413,34 @@ fn cached_has_artist(cached: &CachedTrackMetadata, normalized_artist: &str) -> b .any(|artist| music_dht::normalize_name(artist) == normalized_artist) } +/// Prefer advertised owners, then ask a bounded set of known peers directly. +/// Catalog lookup is useful even before those peers' DHT records arrive. +fn artist_catalog_owners( + items: &[LibraryItem], + normalized: &str, + own: EndpointId, + known: impl IntoIterator, +) -> Vec { + const MAX_CATALOG_PEERS: usize = 32; + let advertised = items + .iter() + .filter(|item| { + (item.kind == ItemKind::Artist && item.normalized_name == normalized) + || item + .artist_names + .iter() + .chain(&item.featured_artist_names) + .any(|artist| music_dht::normalize_name(artist) == normalized) + }) + .map(|item| item.owner); + let mut seen = std::collections::HashSet::from([own]); + advertised + .chain(known) + .filter(|owner| seen.insert(*owner)) + .take(MAX_CATALOG_PEERS) + .collect() +} + fn rank_fed_search_results( artists: &mut [FedArtistHit], tracks: &mut [FedTrack], diff --git a/src/federation/tests.rs b/src/federation/tests.rs index c98985c..742ee2e 100644 --- a/src/federation/tests.rs +++ b/src/federation/tests.rs @@ -93,3 +93,45 @@ fn federation_search_ranks_exact_names_first() { assert_eq!(artists[0].name, "Ежемесячные"); assert_eq!(tracks[0].title, "Ежемесячные"); } + +#[test] +fn artist_catalog_discovery_uses_known_peers_without_dht_hits() { + let own = music_dht::SecretKey::from_bytes(&[8; 32]).public(); + let peer = test_owner(); + assert_eq!( + artist_catalog_owners(&[], "artist", own, [own, peer, peer]), + vec![peer] + ); + // Unrelated records must not send the card request to their owners. + assert!(artist_catalog_owners(&[dht_track(&["Other"], &[])], "artist", own, []).is_empty()); +} + +#[test] +fn artist_catalog_discovery_prioritizes_matching_owners_and_bounds_fanout() { + let own = music_dht::SecretKey::from_bytes(&[8; 32]).public(); + let peer = test_owner(); + let known: Vec<_> = (10..60) + .map(|seed| music_dht::SecretKey::from_bytes(&[seed; 32]).public()) + .collect(); + for item in [ + dht_track(&["Artist"], &[]), + dht_track(&["Host"], &["Artist"]), + ] { + let owners = artist_catalog_owners( + &[item], + "artist", + own, + known.iter().copied().chain([own, peer]), + ); + assert_eq!(owners.len(), 32); + assert_eq!(owners[0], peer); + assert!(!owners.contains(&own)); + assert_eq!( + owners + .iter() + .collect::>() + .len(), + owners.len() + ); + } +}