Document podcast contract and bump crate versions
Add PODCASTS.md as the normative podcast contract: identity and URL canonicalization, the no-GUID rule, synced versus local versus public data, operation kinds and merge rules with examples, snapshot recovery, version gating for peers below v4, Jam privacy and the reserved playback_rate. Update PLAYBACK_PROTOCOL.md, ARCHITECTURE.md, the crate READMEs and CHANGELOG.md. Bump music-dht to 0.6.0 and furumi-library to 0.3.0: new public enum variants and struct fields are breaking changes for 0.x, and furumi-library re-exposes music-dht types. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
2d4782819d
commit
4f7e999280
12 files changed
+563
-10
No files matched your search
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "furumi-library"
|
||||
version = "0.2.0"
|
||||
version = "0.3.0"
|
||||
description = "Client-independent SQLite music library for Furumi players"
|
||||
readme = "README.md"
|
||||
documentation = "https://docs.rs/furumi-library"
|
||||
|
||||
@@ -19,3 +19,7 @@ publication, clients can depend on the released crate version instead.
|
||||
`Library::open(default_db_path()?)` opens the same platform-native Furumi
|
||||
library used by every client. Connections use WAL, foreign keys, and a busy
|
||||
timeout so independently running clients can safely share the database.
|
||||
|
||||
Version 0.3 follows `music-dht` 0.6, whose device-sync and podcast contract
|
||||
types it re-exposes. Podcast persistence is not part of this release; it will
|
||||
implement the rules of the workspace `PODCASTS.md`.
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "music-dht"
|
||||
version = "0.5.0"
|
||||
version = "0.6.0"
|
||||
description = "Distributed music library search: a Kademlia-style DHT on top of federation-net"
|
||||
readme = "README.md"
|
||||
documentation = "https://docs.rs/music-dht"
|
||||
|
||||
@@ -185,7 +185,9 @@ new clients should accept both ALPNs and only send `ListenRecorded` when
|
||||
`supports_listen_history(peer.protocol_version)` returns true. Likes,
|
||||
playlists and membership remain compatible with v1. Profile version 3 adds
|
||||
versioned personal playback coordination over the existing JSON sync stream;
|
||||
legacy unfenced playback messages are ignored by upgraded clients.
|
||||
legacy unfenced playback messages are ignored by upgraded clients. Profile
|
||||
version 4 adds podcasts (see below); `op_allowed_for_peer` applies all of
|
||||
these rules to one operation.
|
||||
|
||||
`music_dht::playback` provides the shared pure ownership engine and generic
|
||||
snapshot/command envelopes. Configure startup and failover with `Config`, feed
|
||||
@@ -193,12 +195,64 @@ actual output reports, and persist `Checkpoint` before applying decisions.
|
||||
`Config::passive()` is intended for always-running gateways. See the workspace
|
||||
`PLAYBACK_PROTOCOL.md` for invariants, configuration and migration details.
|
||||
|
||||
## Podcasts
|
||||
|
||||
`music_dht::podcast` is the shared, pure podcast contract (no SQLite, HTTP or
|
||||
clock). Clients use it for identity, merge rules and wire DTOs; see the
|
||||
workspace `PODCASTS.md` for the normative rules.
|
||||
|
||||
```rust
|
||||
use music_dht::podcast::{
|
||||
EpisodeIdentityHints, FeedUrl, PodcastId, ProgressRecord, resolve_episode_ids,
|
||||
};
|
||||
|
||||
let url = FeedUrl::from_user_input("feed://example.com/rss?token=abc")?;
|
||||
let podcast = PodcastId::from_feed_url(&url); // "pod1:..."
|
||||
let hints = [EpisodeIdentityHints {
|
||||
guid: Some("episode-1".into()),
|
||||
..Default::default()
|
||||
}];
|
||||
let ids = resolve_episode_ids(&podcast, None, &hints, &[]); // "ep1:..."
|
||||
|
||||
// Explicit actions (seek, start over, new session) bump the generation.
|
||||
let generation = ProgressRecord::explicit_generation(Some(4)); // 5
|
||||
```
|
||||
|
||||
* `FeedUrl` canonicalizes feed URLs and keeps every query parameter.
|
||||
* `PodcastId`, `EpisodeId`, `EpisodeKey`, `resolve_podcast_id`,
|
||||
`merge_feed_aliases`, `resolve_episode_ids`: identity, aliases and the
|
||||
no-GUID rule.
|
||||
* `PodcastMeta`, `EpisodeMeta`, `PodcastEpisodeRef`: bounded metadata and the
|
||||
self-contained queue item.
|
||||
* `SubscriptionRecord`, `ShareRecord`, `ProgressRecord`, `ListenSession` with
|
||||
`merge_subscription`, `merge_share`, `merge_progress`,
|
||||
`merge_listen_session`, `effective_share`, `reaches_completion` and
|
||||
`completed_listen_count`.
|
||||
|
||||
Enable the `podcast-feed` feature for `music_dht::podcast::feed`, the shared
|
||||
tolerant RSS 2.0 / RSS 1.0 / Atom parser:
|
||||
|
||||
```toml
|
||||
music-dht = { version = "0.6", features = ["podcast-feed"] }
|
||||
```
|
||||
|
||||
Device-sync protocol v4 adds `podcast_subscription_set`, `podcast_share_set`,
|
||||
`podcast_progress_set` and `podcast_listen_recorded`, podcast snapshot
|
||||
sections, `PlaybackTrack.source` and a reserved `playback_rate`. Old clients
|
||||
cannot parse these, so always filter with `op_allowed_for_peer`,
|
||||
`playback_allowed_for_peer`, `SyncSnapshot::for_peer` and
|
||||
`playback_command_allowed_from_peer`, using the protocol version each device
|
||||
reported itself (`profile_protocol_version`). Jam hosts use
|
||||
`jam::redact_jam_snapshot`, `jam_command_allowed` and
|
||||
`restore_jam_private_items`.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
cargo fmt --check
|
||||
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
||||
cargo test -p music-dht
|
||||
cargo test -p music-dht --features podcast-feed
|
||||
```
|
||||
|
||||
The integration test starts three real nodes in one process (they use Iroh's
|
||||
|
||||
@@ -23,6 +23,10 @@
|
||||
//! * [`similarity_lsh`] turns those embeddings into deterministic compact
|
||||
//! routing summaries, while [`similarity_dht`] stores and discovers signed
|
||||
//! peer summaries without owning model inference or an embedding database.
|
||||
//! * [`podcast`] is the pure, shared podcast contract (canonical feed URLs,
|
||||
//! podcast/episode ids, metadata DTOs and convergent merge rules), with an
|
||||
//! optional RSS/Atom parser behind the `podcast-feed` feature;
|
||||
//! [`device_sync`] protocol v4 carries it between trusted devices.
|
||||
//! * Records are replicated to the `K` nodes whose ids are XOR-closest to
|
||||
//! each key. Publishers pick the targets from their routing table and send
|
||||
//! batched store requests (one pipeline per peer), so even a large library
|
||||
|
||||
Reference in new issue
Block a user