music_dht/lib.rs
1//! # music-dht
2//!
3//! A distributed music library directory on top of [`federation_net`]:
4//! peers publish their local library (artists, releases, tracks — names and
5//! small metadata, never files) into a Kademlia-style DHT and search each
6//! other's libraries. Every running node is simultaneously a client, a DHT
7//! router and a storage node — there are no dedicated bootstrap, index or
8//! search servers.
9//!
10//! ## How it works
11//!
12//! * Every peer derives a stable 256-bit [`NodeId`] from its persistent
13//! `federation-net` endpoint id.
14//! * [`LibraryItem`] records are published under BLAKE3-derived [`DhtKey`]s:
15//! one exact key for the whole normalized name plus one key per token of
16//! the name, every main/featured artist name and the track's release title
17//! (so a track is found by its artists).
18//! * Track records may also carry a compact `b3:<hex>` content id and are then
19//! published under a content key, so applications can find another peer with
20//! the exact same audio bytes.
21//! * [`similarity`] defines the bounded, model-neutral stream contract used by
22//! clients that independently generate compatible music embeddings.
23//! * [`similarity_lsh`] turns those embeddings into deterministic compact
24//! routing summaries, while [`similarity_dht`] stores and discovers signed
25//! peer summaries without owning model inference or an embedding database.
26//! * Records are replicated to the `K` nodes whose ids are XOR-closest to
27//! each key. Publishers pick the targets from their routing table and send
28//! batched store requests (one pipeline per peer), so even a large library
29//! republishes in seconds; searches discover records with an iterative
30//! Kademlia-style lookup (never a broadcast).
31//! * Peers learn about each other through a Hello/PeerExchange gossip that
32//! runs automatically on every new connection; connections to further
33//! nodes are opened on demand from stored tickets.
34//! * Deletions propagate as tombstones that win over active records of the
35//! same or lower revision; replicas expire by TTL and owners republish
36//! periodically.
37//!
38//! ## Example
39//!
40//! ```no_run
41//! use music_dht::{ItemKind, ItemSpec, MusicDhtConfig, MusicDhtService};
42//! use federation_net::{NetworkId, RendezvousConfig};
43//!
44//! # async fn run() -> music_dht::Result<()> {
45//! let config = MusicDhtConfig::builder()
46//! .data_dir("./peer-a")
47//! .network_id(NetworkId::from_name("my-music-network"))
48//! // Find other peers knowing only the network id.
49//! .rendezvous(RendezvousConfig::default())
50//! .build()?;
51//! let (service, mut events) = MusicDhtService::start(config).await?;
52//!
53//! // Publish (and keep in sync) the local library.
54//! service
55//! .sync_library(vec![ItemSpec {
56//! local_key: "track:42".into(),
57//! kind: ItemKind::Track,
58//! name: "Teardrop".into(),
59//! artist_names: vec!["Massive Attack".into()],
60//! featured_artist_names: vec![],
61//! year: Some(1998),
62//! release_type: None,
63//! release_title: Some("Mezzanine".into()),
64//! track_number: Some(10),
65//! disc_number: Some(1),
66//! duration_seconds: Some(330.0),
67//! content_id: None,
68//! }])
69//! .await?;
70//!
71//! // Search the whole network.
72//! let outcome = service.search_network("massive attack").await?;
73//! for item in &outcome.network_results {
74//! println!("{} {} owned by {}", item.kind, item.name, item.owner);
75//! }
76//! # while let Some(event) = events.recv().await { drop(event); }
77//! # service.shutdown().await
78//! # }
79//! ```
80
81#![warn(missing_docs)]
82#![forbid(unsafe_code)]
83
84pub mod capabilities;
85pub mod catalog;
86mod config;
87mod database;
88pub mod device_sync;
89mod dht;
90mod error;
91pub mod jam;
92mod message;
93mod node;
94mod normalization;
95mod record;
96mod request;
97mod routing;
98mod service;
99pub mod similarity;
100pub mod similarity_dht;
101pub mod similarity_lsh;
102
103pub use similarity_lsh::SimilarityRouteEntry;
104
105pub use config::{
106 DEFAULT_EXPIRE_INTERVAL, DEFAULT_LOOKUP_TIMEOUT, DEFAULT_REPUBLISH_INTERVAL,
107 DEFAULT_REQUEST_TIMEOUT, DEFAULT_TRANSPORT_TIMEOUT, MusicDhtConfig, MusicDhtConfigBuilder,
108};
109pub use database::MusicDhtStorage;
110pub use dht::{StoreDecision, decide_store};
111pub use error::{MusicDhtError, Result};
112pub use message::{
113 DHT_PROTOCOL_VERSION, FindNodeRequest, FindNodeResponse, FindValueRequest, FindValueResponse,
114 Hello, MAX_PEER_EXCHANGE_CONTACTS, MAX_RECORDS_PER_BATCH, MAX_RECORDS_PER_RESPONSE,
115 MusicDhtMessage, PeerExchange, PingRequest, PongResponse, RequestEnvelope, RequestId,
116 ResponseEnvelope, StoreBatchRequest, StoreBatchResponse, StoreRecordRequest,
117};
118pub use normalization::{normalize_name, tokenize};
119pub use record::{
120 ACTIVE_RECORD_TTL, DhtKey, ItemId, ItemKind, LibraryItem, MAX_ARTISTS_PER_ITEM,
121 MAX_CONTENT_ID_BYTES, MAX_ITEM_NAME_BYTES, MAX_TOKENS_PER_ITEM, PeerId, StoredRecord,
122 TOMBSTONE_TTL, normalize_content_id,
123};
124pub use request::MAX_PENDING_REQUESTS;
125pub use routing::{
126 ALPHA, Distance, K, MAX_LOOKUP_REQUESTS, NodeContact, NodeId, RoutingTable, distance,
127 key_distance,
128};
129pub use service::{
130 ItemSpec, MusicDhtEvent, MusicDhtEventReceiver, MusicDhtService, PublishStats, SCHEMA_NAME,
131 SearchOutcome, SyncStats,
132};
133
134// Re-exported types from the transport layer that appear in this API.
135pub use federation_net::{
136 ByteStream, ByteStreamConnectionStats, ConnectionPathKind, EndpointAddr, EndpointId,
137 NetworkHealthSnapshot, NetworkHealthState, NetworkId, PeerTicket, RecvStream, RendezvousConfig,
138 SecretKey, SendStream, StreamAcceptor,
139};
140
141pub mod playback;