Files
frid/crates/music-dht/src/podcast/mod.rs
T
sanapachandClaude Opus 5.5 085bff6191 Harden podcast sync registers, versions and snapshots
- Order subscription and share registers by a per-podcast Lamport
  generation before hlc_ms (next_podcast_generation), so clock skew
  cannot undo an observed unsubscribe or share decision.
- share=false is register state, not a compactable tombstone.
- Add podcast_feed_aliases_added so refreshes can sync aliases without
  touching the registers; SubscriptionRecord::feed_urls keeps the current
  feed URL resolvable beyond the alias bound.
- Carry progress_generation on queue items for handoff.
- Distinguish self-reported and relayed peer versions, and gate
  PairRequest by an optional inviter version in InviteWire.
- Give each podcast snapshot section its own byte budget, drop channel
  descriptions from snapshots and allow a caller-provided budget.
- Reject one-slash http(s) typos in FeedUrl::from_user_input.
- Pin that malformed ids and feed URLs reject the whole message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 16:10:33 +02:00

311 lines
12 KiB
Rust

//! Shared podcast contract for Furumi clients.
//!
//! This module is pure: it has no SQLite, HTTP, clock, audio or UI
//! dependency. Every Furumi client (TUI, web, desktop) uses it so that
//! podcast identity, normalization, merge rules and wire DTOs are defined
//! exactly once. The normative description lives in the workspace
//! `PODCASTS.md`; this documentation summarizes the API.
//!
//! # Identity
//!
//! * [`FeedUrl`] is a canonical feed URL. [`FeedUrl::parse`] lowercases the
//! scheme and host, drops a default port and the fragment, and keeps the
//! path and **every** query parameter byte-for-byte (only non-ASCII bytes
//! are percent-encoded). Non-`http(s)` URLs, userinfo and whitespace are
//! rejected. [`FeedUrl::from_user_input`] additionally accepts the
//! `feed:`/`podcast:`/`pcast:`/`itpc:` forms and a missing scheme.
//! * [`PodcastId`] is `pod1:` followed by the lowercase base32 BLAKE3 hash of
//! `"furumi-podcast:podcast:v1\0"` and the canonical feed URL. It is
//! derived once, from the URL of the first subscription; later URLs
//! (redirects, `itunes:new-feed-url`) become feed aliases resolved by
//! [`resolve_podcast_id`].
//! * [`EpisodeId`] is `ep1:` followed by the lowercase base32 BLAKE3 hash of
//! `"furumi-podcast:episode:v1\0"`, the podcast id and a key. The key is
//! the RSS GUID when present. Without a GUID, [`resolve_episode_ids`] first
//! reuses the id of a known episode that matches by enclosure URL, `<link>`
//! or (date, normalized title) and only then derives a new id from the
//! first available fallback key.
//!
//! # Personal state
//!
//! * [`SubscriptionRecord`]: last-writer-wins by `(generation, hlc_ms, op_id)`
//! where `generation` is a per-podcast Lamport counter
//! ([`next_podcast_generation`]); unsubscribing is state, not a tombstone.
//! Feed aliases merge as a bounded grow-only set.
//! * [`ShareRecord`]: last-writer-wins with the same ordering; `shared = false`
//! is register state that is never compacted. See [`effective_share`] for
//! the rule that a (re)subscription is private.
//! * [`ProgressRecord`]: register ordered by
//! `(generation, hlc_ms, device_id, op_id)`. Explicit user actions bump the
//! generation to `max_seen + 1`; periodic checkpoints keep the generation of
//! their session, so a late checkpoint of an old session always loses.
//! * [`ListenSession`]: grow-only set keyed by `session_id`; one completion per
//! session, so re-delivery never double counts.
//!
//! # Queue items
//!
//! [`PodcastEpisodeRef`] is the bounded, self-contained reference carried by
//! playback queues and progress operations. A receiving device can show and
//! play the episode without being subscribed to the podcast.
//!
//! # Feed parser
//!
//! With the `podcast-feed` cargo feature, `feed` provides the shared tolerant
//! RSS 2.0 / RSS 1.0 / Atom parser that produces the identity hints consumed
//! by [`resolve_episode_ids`].
//!
//! ```
//! use music_dht::podcast::{EpisodeId, FeedUrl, PodcastId};
//!
//! let url = FeedUrl::parse("HTTPS://Example.COM:443/feed.xml?token=Ab#top").unwrap();
//! assert_eq!(url.as_str(), "https://example.com/feed.xml?token=Ab");
//! let podcast = PodcastId::from_feed_url(&url);
//! assert!(podcast.as_str().starts_with("pod1:"));
//! let episode = EpisodeId::from_guid(&podcast, "episode-42").unwrap();
//! assert!(episode.as_str().starts_with("ep1:"));
//! ```
mod feed_url;
mod id;
mod identity;
mod meta;
mod state;
#[cfg(feature = "podcast-feed")]
pub mod feed;
pub use feed_url::{FeedUrl, merge_feed_aliases, resolve_podcast_id};
pub use id::{
EPISODE_ID_DOMAIN, EPISODE_ID_PREFIX, EpisodeId, EpisodeKey, PODCAST_ID_DOMAIN,
PODCAST_ID_PREFIX, PodcastId,
};
pub use identity::{
EpisodeIdentityHints, KnownEpisode, normalize_episode_title, resolve_episode_id,
resolve_episode_ids,
};
pub use meta::{EpisodeMeta, EpisodeType, PodcastEpisodeRef, PodcastMeta};
pub use state::{
COMPLETION_TAIL_MAX_MS, ListenSession, MIN_RECORDED_EPISODE_LISTEN_MS, ProgressRecord,
ProgressStatus, ShareRecord, SubscriptionRecord, completed_listen_count, effective_share,
merge_listen_session, merge_progress, merge_share, merge_subscription, next_podcast_generation,
reaches_completion,
};
/// Maximum characters of a title (podcast, episode, author).
pub const MAX_TITLE_CHARS: usize = 1_000;
/// Maximum characters of a podcast or episode description.
pub const MAX_DESCRIPTION_CHARS: usize = 4_000;
/// Maximum bytes of any URL carried by the contract.
pub const MAX_URL_BYTES: usize = 2_048;
/// Maximum bytes of an RSS GUID. Longer GUIDs are treated as absent.
pub const MAX_GUID_BYTES: usize = 2_048;
/// Maximum bytes of a MIME type.
pub const MAX_MIME_BYTES: usize = 128;
/// Maximum bytes of a device, session or operation id.
pub const MAX_TOKEN_BYTES: usize = 256;
/// Maximum feed aliases kept per podcast, besides the URL the id was derived from.
pub const MAX_FEED_ALIASES: usize = 8;
/// Maximum subscription records in one sync snapshot.
pub const MAX_SNAPSHOT_SUBSCRIPTIONS: usize = 1_000;
/// Maximum share records in one sync snapshot.
pub const MAX_SNAPSHOT_SHARES: usize = 1_000;
/// Maximum progress registers in one sync snapshot.
pub const MAX_SNAPSHOT_PROGRESS: usize = 5_000;
/// Maximum listening sessions in one sync snapshot.
pub const MAX_SNAPSHOT_LISTEN_SESSIONS: usize = 2_000;
/// Serialized JSON budget shared by all podcast snapshot sections.
///
/// It leaves room for music state inside the 8 MiB sync line limit.
pub const MAX_PODCAST_SNAPSHOT_BYTES: usize = 4 * 1024 * 1024;
/// Errors produced by podcast contract validation and parsing.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[non_exhaustive]
pub enum PodcastError {
/// A feed URL cannot be canonicalized.
#[error("invalid feed URL: {0}")]
InvalidFeedUrl(String),
/// A string is not a valid podcast or episode id.
#[error("invalid {kind} id")]
InvalidId {
/// `podcast` or `episode`.
kind: &'static str,
},
/// A field violates the contract (missing, too long, malformed).
#[error("invalid {field}: {reason}")]
InvalidField {
/// Field name.
field: &'static str,
/// Human-readable reason.
reason: &'static str,
},
/// Two records that must describe the same entity do not.
#[error("cannot merge records of different {0}")]
Mismatch(&'static str),
/// The document is not an RSS or Atom feed.
#[error("not an RSS or Atom feed{0}")]
NotAFeed(String),
/// The feed is malformed and nothing usable could be parsed.
#[error("malformed feed: {0}")]
MalformedFeed(String),
}
/// Result alias for this module.
pub type PodcastResult<T> = std::result::Result<T, PodcastError>;
/// Truncates `text` to at most `max_chars` characters, ending with `…` when cut.
///
/// Clients use it to fit publisher metadata into the contract bounds.
pub fn bounded_text(text: &str, max_chars: usize) -> String {
if text.chars().count() <= max_chars {
return text.to_string();
}
if max_chars == 0 {
return String::new();
}
let mut out: String = text.chars().take(max_chars - 1).collect();
out.push('…');
out
}
pub(crate) fn check_text(
field: &'static str,
value: &str,
max_chars: usize,
required: bool,
) -> PodcastResult<()> {
if required && value.trim().is_empty() {
return Err(PodcastError::InvalidField {
field,
reason: "must not be empty",
});
}
if value.len() > max_chars * 4 || value.chars().count() > max_chars {
return Err(PodcastError::InvalidField {
field,
reason: "is too long",
});
}
Ok(())
}
pub(crate) fn check_opt_text(
field: &'static str,
value: Option<&str>,
max_chars: usize,
) -> PodcastResult<()> {
value.map_or(Ok(()), |value| check_text(field, value, max_chars, false))
}
pub(crate) fn check_token(field: &'static str, value: &str) -> PodcastResult<()> {
if value.is_empty() {
return Err(PodcastError::InvalidField {
field,
reason: "must not be empty",
});
}
if value.len() > MAX_TOKEN_BYTES {
return Err(PodcastError::InvalidField {
field,
reason: "is too long",
});
}
if value.chars().any(|c| c.is_control()) {
return Err(PodcastError::InvalidField {
field,
reason: "contains control characters",
});
}
Ok(())
}
/// Returns whether `value` is an absolute `http`/`https` URL with a host,
/// without whitespace or control characters and within [`MAX_URL_BYTES`].
///
/// Media URLs keep the publisher's spelling; only feed URLs are canonicalized.
pub fn is_http_url(value: &str) -> bool {
if value.is_empty()
|| value.len() > MAX_URL_BYTES
|| value.chars().any(|c| c.is_whitespace() || c.is_control())
{
return false;
}
let lower_prefix = |prefix: &str| {
value.len() >= prefix.len() && value[..prefix.len()].eq_ignore_ascii_case(prefix)
};
let rest = if lower_prefix("http://") {
&value[7..]
} else if lower_prefix("https://") {
&value[8..]
} else {
return false;
};
let authority = rest.split(['/', '?', '#']).next().unwrap_or_default();
let host = authority.rsplit('@').next().unwrap_or_default();
!host.is_empty() && !host.starts_with(':')
}
pub(crate) fn check_url(field: &'static str, value: &str) -> PodcastResult<()> {
if is_http_url(value) {
Ok(())
} else {
Err(PodcastError::InvalidField {
field,
reason: "must be an absolute http(s) URL",
})
}
}
pub(crate) fn check_opt_url(field: &'static str, value: Option<&str>) -> PodcastResult<()> {
value.map_or(Ok(()), |value| check_url(field, value))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn bounded_text_cuts_on_char_boundaries() {
assert_eq!(bounded_text("hello", 5), "hello");
assert_eq!(bounded_text("hello!", 5), "hell…");
assert_eq!(bounded_text("привет", 3), "пр…");
assert_eq!(bounded_text("x", 0), "");
}
#[test]
fn text_limits_accept_the_limit_and_reject_one_more() {
let at = "я".repeat(MAX_TITLE_CHARS);
let over = "я".repeat(MAX_TITLE_CHARS + 1);
assert!(check_text("title", &at, MAX_TITLE_CHARS, true).is_ok());
assert!(check_text("title", &over, MAX_TITLE_CHARS, true).is_err());
assert!(check_text("title", " ", MAX_TITLE_CHARS, true).is_err());
assert!(check_text("title", "", MAX_TITLE_CHARS, false).is_ok());
}
#[test]
fn token_limits() {
assert!(check_token("op_id", &"a".repeat(MAX_TOKEN_BYTES)).is_ok());
assert!(check_token("op_id", &"a".repeat(MAX_TOKEN_BYTES + 1)).is_err());
assert!(check_token("op_id", "").is_err());
assert!(check_token("op_id", "a\nb").is_err());
}
#[test]
fn http_urls() {
assert!(is_http_url("https://cdn.example.test/a.mp3?x=1"));
assert!(is_http_url("HTTP://cdn.example.test"));
assert!(!is_http_url("ftp://cdn.example.test/a.mp3"));
assert!(!is_http_url("file:///etc/passwd"));
assert!(!is_http_url("https://"));
assert!(!is_http_url("https:///path"));
assert!(!is_http_url("https://a.test/my file.mp3"));
assert!(!is_http_url(""));
let long = format!("https://a.test/{}", "x".repeat(MAX_URL_BYTES));
assert!(!is_http_url(&long));
let at = format!("https://a.test/{}", "x".repeat(MAX_URL_BYTES - 15));
assert_eq!(at.len(), MAX_URL_BYTES);
assert!(is_http_url(&at));
}
}