Skip to main content

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;