diff --git a/crates/music-dht/src/lib.rs b/crates/music-dht/src/lib.rs index f9b8500..669e751 100644 --- a/crates/music-dht/src/lib.rs +++ b/crates/music-dht/src/lib.rs @@ -92,6 +92,7 @@ pub mod jam; mod message; mod node; mod normalization; +pub mod podcast; mod record; mod request; mod routing; diff --git a/crates/music-dht/src/podcast/feed_url.rs b/crates/music-dht/src/podcast/feed_url.rs new file mode 100644 index 0000000..ea13774 --- /dev/null +++ b/crates/music-dht/src/podcast/feed_url.rs @@ -0,0 +1,507 @@ +//! Feed URL canonicalization and feed aliases. + +use std::collections::BTreeSet; +use std::fmt; + +use serde::{Deserialize, Serialize}; + +use super::{MAX_FEED_ALIASES, MAX_URL_BYTES, PodcastError, PodcastId, PodcastResult}; + +/// Canonical podcast feed URL. +/// +/// Canonicalization ([`FeedUrl::parse`]) is deliberately small so that every +/// client, whatever its URL library, produces the same bytes: +/// +/// 1. Only `http://` and `https://` (any case) are accepted; the scheme is +/// lowercased. +/// 2. Userinfo (`user:pass@`), whitespace, control characters and `\` are +/// rejected. +/// 3. The host is lowercased. Non-ASCII hosts are rejected: pass the IDNA +/// (`xn--`) form, as produced by WHATWG URL parsers. IPv6 literals are +/// accepted in brackets. +/// 4. An empty port and the scheme's default port (80, 443) are dropped; +/// other ports lose leading zeros. +/// 5. The fragment is dropped. +/// 6. An empty path becomes `/`. The path and the **whole** query string are +/// otherwise kept byte-for-byte, including parameter order, case and +/// percent-encoding; only non-ASCII bytes are percent-encoded (`%XX`, +/// uppercase hex) so the result is ASCII. +/// +/// The canonical form is at most [`MAX_URL_BYTES`] bytes and canonicalizing it +/// again is the identity. Deserialization accepts only canonical strings. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)] +#[serde(try_from = "String", into = "String")] +pub struct FeedUrl(String); + +impl FeedUrl { + /// Canonicalizes an absolute `http(s)` feed URL. + pub fn parse(input: &str) -> PodcastResult { + canonicalize(input).map(Self) + } + + /// Canonicalizes a URL typed or pasted by a user. + /// + /// Surrounding whitespace is trimmed, `feed:`, `podcast:`, `pcast:` and + /// `itpc:` prefixes map to `https://` (or to the embedded `http(s)` URL), + /// and input without a scheme defaults to `https://`. + pub fn from_user_input(input: &str) -> PodcastResult { + let trimmed = input.trim(); + if trimmed.is_empty() { + return Err(invalid("feed URL is empty")); + } + let lower = trimmed.to_ascii_lowercase(); + let mut candidate = trimmed.to_string(); + for scheme in ["feed:", "podcast:", "pcast:", "itpc:"] { + if lower.starts_with(scheme) { + let rest = &trimmed[scheme.len()..]; + let rest_lower = rest.to_ascii_lowercase(); + candidate = + if rest_lower.starts_with("http://") || rest_lower.starts_with("https://") { + rest.to_string() + } else { + format!("https://{}", rest.trim_start_matches('/')) + }; + break; + } + } + if !has_scheme(&candidate) { + candidate = format!("https://{candidate}"); + } + Self::parse(&candidate) + } + + /// Canonical string form. + pub fn as_str(&self) -> &str { + &self.0 + } +} + +impl fmt::Display for FeedUrl { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&self.0) + } +} + +impl TryFrom for FeedUrl { + type Error = PodcastError; + + fn try_from(value: String) -> PodcastResult { + if canonicalize(&value)? == value { + Ok(Self(value)) + } else { + Err(invalid("feed URL is not in canonical form")) + } + } +} + +impl From for String { + fn from(value: FeedUrl) -> String { + value.0 + } +} + +impl AsRef for FeedUrl { + fn as_ref(&self) -> &str { + &self.0 + } +} + +fn invalid(reason: &str) -> PodcastError { + PodcastError::InvalidFeedUrl(reason.to_string()) +} + +fn has_scheme(text: &str) -> bool { + let Some((scheme, rest)) = text.split_once(':') else { + return false; + }; + let mut chars = scheme.chars(); + chars.next().is_some_and(|c| c.is_ascii_alphabetic()) + && chars.all(|c| c.is_ascii_alphanumeric() || matches!(c, '+' | '-' | '.')) + && rest.starts_with("//") +} + +fn canonicalize(input: &str) -> PodcastResult { + if input.len() > MAX_URL_BYTES * 3 { + return Err(invalid("feed URL is too long")); + } + if input.chars().any(|c| c.is_whitespace() || c.is_control()) { + return Err(invalid("feed URL must not contain whitespace")); + } + if input.contains('\\') { + return Err(invalid("feed URL must not contain '\\'")); + } + let (scheme, rest) = input + .split_once("://") + .ok_or_else(|| invalid("feed URL must start with http:// or https://"))?; + let (scheme, default_port) = if scheme.eq_ignore_ascii_case("http") { + ("http", 80) + } else if scheme.eq_ignore_ascii_case("https") { + ("https", 443) + } else { + return Err(invalid("only http and https feed URLs are supported")); + }; + let authority_end = rest.find(['/', '?', '#']).unwrap_or(rest.len()); + let (authority, tail) = rest.split_at(authority_end); + if authority.contains('@') { + return Err(invalid("feed URL must not contain credentials")); + } + let (host, port) = split_host_port(authority)?; + let host = canonical_host(host)?; + let port = match port { + None | Some("") => None, + Some(port) => { + if port.len() > 5 || !port.bytes().all(|b| b.is_ascii_digit()) { + return Err(invalid("invalid feed URL port")); + } + match port.parse::() { + Ok(value) if (1..=65_535).contains(&value) => { + (value != default_port).then_some(value) + } + _ => return Err(invalid("invalid feed URL port")), + } + } + }; + let tail = tail.split('#').next().unwrap_or_default(); + let (path, query) = match tail.find('?') { + Some(at) => tail.split_at(at), + None => (tail, ""), + }; + let mut out = String::with_capacity(input.len() + 8); + out.push_str(scheme); + out.push_str("://"); + out.push_str(&host); + if let Some(port) = port { + out.push(':'); + out.push_str(&port.to_string()); + } + if path.is_empty() { + out.push('/'); + } else { + push_ascii(&mut out, path); + } + push_ascii(&mut out, query); + if out.len() > MAX_URL_BYTES { + return Err(invalid("feed URL is too long")); + } + Ok(out) +} + +fn split_host_port(authority: &str) -> PodcastResult<(&str, Option<&str>)> { + if authority.starts_with('[') { + let close = authority + .find(']') + .ok_or_else(|| invalid("unterminated IPv6 host"))?; + let (host, after) = authority.split_at(close + 1); + return match after { + "" => Ok((host, None)), + _ => after + .strip_prefix(':') + .map(|port| (host, Some(port))) + .ok_or_else(|| invalid("invalid feed URL host")), + }; + } + Ok(match authority.rsplit_once(':') { + Some((host, port)) => (host, Some(port)), + None => (authority, None), + }) +} + +fn canonical_host(host: &str) -> PodcastResult { + if host.is_empty() { + return Err(invalid("feed URL has no host")); + } + if !host.is_ascii() { + return Err(invalid( + "feed URL host must be ASCII (use the IDNA xn-- form)", + )); + } + if let Some(inner) = host.strip_prefix('[').and_then(|h| h.strip_suffix(']')) { + if inner.is_empty() + || !inner + .bytes() + .all(|b| b.is_ascii_hexdigit() || matches!(b, b':' | b'.')) + { + return Err(invalid("invalid IPv6 host")); + } + return Ok(host.to_ascii_lowercase()); + } + if !host + .bytes() + .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'.' | b'_')) + || !host.bytes().any(|b| b.is_ascii_alphanumeric()) + { + return Err(invalid("invalid feed URL host")); + } + Ok(host.to_ascii_lowercase()) +} + +fn push_ascii(out: &mut String, value: &str) { + for ch in value.chars() { + if ch.is_ascii() { + out.push(ch); + } else { + let mut buf = [0u8; 4]; + for byte in ch.encode_utf8(&mut buf).bytes() { + out.push_str(&format!("%{byte:02X}")); + } + } + } +} + +/// Resolves the podcast a canonical feed URL belongs to. +/// +/// `known` yields `(podcast_id, url)` pairs of every URL already associated +/// with a podcast: the URL of its first subscription, its current fetch URL +/// and its feed aliases. When `url` matches, the existing id is returned (the +/// smallest id if, after a concurrent offline subscription, several podcasts +/// share the URL). Otherwise a new id is derived from `url`. +/// +/// Re-subscribing through a redirect target or an `itunes:new-feed-url` +/// therefore reuses the original podcast, its progress and its history. +pub fn resolve_podcast_id<'a>( + url: &FeedUrl, + known: impl IntoIterator, +) -> PodcastId { + known + .into_iter() + .filter(|(_, alias)| *alias == url) + .map(|(id, _)| id) + .min() + .cloned() + .unwrap_or_else(|| PodcastId::from_feed_url(url)) +} + +/// Merges two feed alias sets of `podcast` as a bounded grow-only set. +/// +/// The result is sorted and duplicate-free. The URL from which `podcast` was +/// derived is always kept; of the other URLs the [`MAX_FEED_ALIASES`] +/// lexicographically smallest are kept. Taking the smallest `k` elements of a +/// union is commutative, associative and idempotent, so devices converge +/// regardless of delivery order. +pub fn merge_feed_aliases(podcast: &PodcastId, a: &[FeedUrl], b: &[FeedUrl]) -> Vec { + let mut origin = None; + let mut rest = BTreeSet::new(); + for url in a.iter().chain(b) { + if PodcastId::from_feed_url(url) == *podcast { + origin = Some(url.clone()); + } else { + rest.insert(url.clone()); + } + } + let mut out: Vec = rest.into_iter().take(MAX_FEED_ALIASES).collect(); + if let Some(origin) = origin { + out.push(origin); + out.sort(); + } + out +} + +#[cfg(test)] +mod tests { + use super::*; + + fn canon(input: &str) -> String { + FeedUrl::parse(input).unwrap().as_str().to_string() + } + + #[test] + fn canonicalization_rules() { + let cases = [ + ( + "https://example.com/feed.xml", + "https://example.com/feed.xml", + ), + ( + "HTTPS://Example.COM/Feed.XML", + "https://example.com/Feed.XML", + ), + ("http://example.com:80/rss", "http://example.com/rss"), + ("https://example.com:443/rss", "https://example.com/rss"), + ("http://example.com:443/rss", "http://example.com:443/rss"), + ( + "https://example.com:08080/rss", + "https://example.com:8080/rss", + ), + ("https://example.com:/rss", "https://example.com/rss"), + ("https://example.com", "https://example.com/"), + ("https://example.com?x=1", "https://example.com/?x=1"), + ("https://example.com/rss#latest", "https://example.com/rss"), + ("https://example.com/rss?#x", "https://example.com/rss?"), + ( + "https://example.com/a/../b/./c?b=2&a=1&A=%2f&token=XyZ", + "https://example.com/a/../b/./c?b=2&a=1&A=%2f&token=XyZ", + ), + ( + "https://example.com/rss?url=https://other.test/x?y#frag", + "https://example.com/rss?url=https://other.test/x?y", + ), + ( + "https://example.com/подкаст?q=ё", + "https://example.com/%D0%BF%D0%BE%D0%B4%D0%BA%D0%B0%D1%81%D1%82?q=%D1%91", + ), + ( + "https://[2001:DB8::1]:443/feed", + "https://[2001:db8::1]/feed", + ), + ("https://[::1]:8443/feed", "https://[::1]:8443/feed"), + ( + "https://xn--d1acufc.xn--p1ai/rss", + "https://xn--d1acufc.xn--p1ai/rss", + ), + ( + "https://my_host.example./rss", + "https://my_host.example./rss", + ), + ]; + for (input, expected) in cases { + assert_eq!(canon(input), expected, "{input:?}"); + // Idempotent. + assert_eq!(canon(expected), expected, "{expected:?}"); + } + } + + #[test] + fn rejected_urls() { + for bad in [ + "", + "example.com/feed", + "ftp://example.com/feed", + "file:///etc/passwd", + "javascript:alert(1)", + "https://", + "https:///path", + "https://user:pass@example.com/feed", + "https://token@example.com/feed", + "https://example.com/my feed", + " https://example.com/feed", + "https://example.com/feed\n", + "https://example.com\\feed", + "https://пример.рф/rss", + "https://example.com:0/rss", + "https://example.com:65536/rss", + "https://example.com:12a/rss", + "https://[::1/feed", + "https://[zz]/feed", + "https://exa%6dple.com/feed", + "https://.../feed", + ] { + assert!(FeedUrl::parse(bad).is_err(), "{bad:?}"); + } + } + + #[test] + fn length_limit_is_inclusive() { + let prefix = "https://a.test/"; + let at = format!("{prefix}{}", "x".repeat(MAX_URL_BYTES - prefix.len())); + assert_eq!(canon(&at).len(), MAX_URL_BYTES); + let over = format!("{at}x"); + assert!(FeedUrl::parse(&over).is_err()); + } + + #[test] + fn user_input_forms() { + let ok = [ + ( + "https://podster.test/rss.xml?pid=778", + "https://podster.test/rss.xml?pid=778", + ), + (" http://a.test/feed ", "http://a.test/feed"), + ("a.test/feed.xml", "https://a.test/feed.xml"), + ("feed://a.test/rss", "https://a.test/rss"), + ("feed:https://a.test/rss", "https://a.test/rss"), + ("podcast://a.test/rss", "https://a.test/rss"), + ("itpc://a.test/rss", "https://a.test/rss"), + ("HTTPS://A.TEST/Feed", "https://a.test/Feed"), + ("a.test:8080/rss", "https://a.test:8080/rss"), + ( + "example.test/rss?src=https://other.test", + "https://example.test/rss?src=https://other.test", + ), + ( + "localhost:8080/feed?u=http://x.test/", + "https://localhost:8080/feed?u=http://x.test/", + ), + ]; + for (input, expected) in ok { + assert_eq!( + FeedUrl::from_user_input(input).unwrap().as_str(), + expected, + "{input:?}" + ); + } + for bad in [ + "", + " ", + "ftp://a.test/feed", + "https://a.test/my feed", + "https://", + "file:///etc/passwd", + "javascript:alert(1)", + ] { + assert!(FeedUrl::from_user_input(bad).is_err(), "{bad:?}"); + } + } + + #[test] + fn deserialization_requires_canonical_form() { + let url = FeedUrl::parse("https://example.com/rss").unwrap(); + let json = serde_json::to_string(&url).unwrap(); + assert_eq!(serde_json::from_str::(&json).unwrap(), url); + assert!(serde_json::from_str::("\"HTTPS://example.com/rss\"").is_err()); + assert!(serde_json::from_str::("\"https://example.com/rss#x\"").is_err()); + assert!(serde_json::from_str::("\"ftp://example.com/rss\"").is_err()); + } + + #[test] + fn query_parameters_change_identity() { + let a = PodcastId::from_feed_url(&FeedUrl::parse("https://a.test/rss?id=1").unwrap()); + let b = PodcastId::from_feed_url(&FeedUrl::parse("https://a.test/rss?id=2").unwrap()); + let c = PodcastId::from_feed_url(&FeedUrl::parse("HTTPS://A.test:443/rss?id=1#x").unwrap()); + assert_ne!(a, b); + assert_eq!(a, c); + } + + #[test] + fn aliases_resolve_to_the_original_podcast() { + let original = FeedUrl::parse("http://old.test/feed").unwrap(); + let moved = FeedUrl::parse("https://new.test/feed").unwrap(); + let id = PodcastId::from_feed_url(&original); + let known = [(&id, &original), (&id, &moved)]; + assert_eq!(resolve_podcast_id(&moved, known), id); + assert_eq!(resolve_podcast_id(&original, known), id); + let unrelated = FeedUrl::parse("https://other.test/feed").unwrap(); + assert_eq!( + resolve_podcast_id(&unrelated, known), + PodcastId::from_feed_url(&unrelated) + ); + // Ambiguity after concurrent offline subscriptions resolves to the + // smallest id, independent of iteration order. + let other = PodcastId::from_feed_url(&moved); + let ambiguous = [(&id, &moved), (&other, &moved)]; + let reversed = [(&other, &moved), (&id, &moved)]; + let expected = (&id).min(&other).clone(); + assert_eq!(resolve_podcast_id(&moved, ambiguous), expected); + assert_eq!(resolve_podcast_id(&moved, reversed), expected); + } + + #[test] + fn alias_merge_is_a_bounded_semilattice() { + let origin = FeedUrl::parse("https://zzz.test/origin").unwrap(); + let id = PodcastId::from_feed_url(&origin); + let urls: Vec = (0..(MAX_FEED_ALIASES + 4)) + .map(|i| FeedUrl::parse(&format!("https://a.test/{i:02}")).unwrap()) + .collect(); + let a: Vec = urls[..5].to_vec(); + let b: Vec = urls[3..].iter().cloned().chain([origin.clone()]).collect(); + let c: Vec = urls[7..].to_vec(); + let ab = merge_feed_aliases(&id, &a, &b); + assert_eq!(ab, merge_feed_aliases(&id, &b, &a)); + assert_eq!(ab, merge_feed_aliases(&id, &ab, &ab)); + let left = merge_feed_aliases(&id, &ab, &c); + let right = merge_feed_aliases(&id, &a, &merge_feed_aliases(&id, &b, &c)); + assert_eq!(left, right); + assert_eq!(left.len(), MAX_FEED_ALIASES + 1); + assert!(left.contains(&origin)); + assert!(left.windows(2).all(|w| w[0] < w[1])); + } +} diff --git a/crates/music-dht/src/podcast/id.rs b/crates/music-dht/src/podcast/id.rs new file mode 100644 index 0000000..976ab3d --- /dev/null +++ b/crates/music-dht/src/podcast/id.rs @@ -0,0 +1,343 @@ +//! Cross-device podcast and episode identifiers. + +use std::fmt; +use std::str::FromStr; + +use serde::{Deserialize, Serialize}; + +use super::{FeedUrl, MAX_GUID_BYTES, PodcastError, PodcastResult}; + +/// BLAKE3 derivation domain of [`PodcastId`]. Changing it changes every id. +pub const PODCAST_ID_DOMAIN: &str = "furumi-podcast:podcast:v1"; +/// BLAKE3 derivation domain of [`EpisodeId`]. Changing it changes every id. +pub const EPISODE_ID_DOMAIN: &str = "furumi-podcast:episode:v1"; +/// String prefix of a [`PodcastId`]. +pub const PODCAST_ID_PREFIX: &str = "pod1:"; +/// String prefix of an [`EpisodeId`]. +pub const EPISODE_ID_PREFIX: &str = "ep1:"; + +/// Length of the base32 body: 32 bytes, RFC 4648 lowercase, no padding. +const DIGEST_CHARS: usize = 52; + +fn digest(domain: &str, parts: &[&[u8]]) -> [u8; 32] { + let mut hasher = blake3::Hasher::new(); + hasher.update(domain.as_bytes()); + hasher.update(&[0]); + for part in parts { + hasher.update(part); + } + *hasher.finalize().as_bytes() +} + +fn encode(prefix: &str, digest: &[u8; 32]) -> String { + let mut body = data_encoding::BASE32_NOPAD.encode(digest); + body.make_ascii_lowercase(); + format!("{prefix}{body}") +} + +fn decode(prefix: &str, value: &str) -> Option<[u8; 32]> { + let body = value.strip_prefix(prefix)?; + if body.len() != DIGEST_CHARS + || !body + .bytes() + .all(|b| b.is_ascii_lowercase() || (b'2'..=b'7').contains(&b)) + { + return None; + } + let bytes = data_encoding::BASE32_NOPAD + .decode(body.to_ascii_uppercase().as_bytes()) + .ok()?; + let digest: [u8; 32] = bytes.try_into().ok()?; + // Reject non-canonical trailing bits so every id has one spelling. + (encode(prefix, &digest) == value).then_some(digest) +} + +macro_rules! string_id { + ($name:ident, $prefix:expr, $kind:literal) => { + impl $name { + /// Parses and validates the canonical string form. + pub fn parse(value: &str) -> PodcastResult { + decode($prefix, value) + .map(|_| Self(value.to_string())) + .ok_or(PodcastError::InvalidId { kind: $kind }) + } + + /// Canonical string form. + pub fn as_str(&self) -> &str { + &self.0 + } + + /// The 32-byte BLAKE3 digest encoded in the id. + pub fn digest(&self) -> [u8; 32] { + decode($prefix, &self.0).expect("validated on construction") + } + } + + impl fmt::Display for $name { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&self.0) + } + } + + impl FromStr for $name { + type Err = PodcastError; + + fn from_str(value: &str) -> PodcastResult { + Self::parse(value) + } + } + + impl TryFrom for $name { + type Error = PodcastError; + + fn try_from(value: String) -> PodcastResult { + decode($prefix, &value) + .map(|_| Self(value)) + .ok_or(PodcastError::InvalidId { kind: $kind }) + } + } + + impl From<$name> for String { + fn from(value: $name) -> String { + value.0 + } + } + + impl AsRef for $name { + fn as_ref(&self) -> &str { + &self.0 + } + } + }; +} + +/// Stable cross-device podcast identity: `pod1:<52 lowercase base32 chars>`. +/// +/// Derived as `BLAKE3("furumi-podcast:podcast:v1" || 0x00 || canonical_feed_url)` +/// from the URL used by the **first** subscription. The id never changes when +/// the feed moves; new URLs are recorded as aliases (see +/// [`super::resolve_podcast_id`]). Deserialization validates the format. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)] +#[serde(try_from = "String", into = "String")] +pub struct PodcastId(String); + +string_id!(PodcastId, PODCAST_ID_PREFIX, "podcast"); + +impl PodcastId { + /// Derives the id of a podcast first subscribed through `url`. + pub fn from_feed_url(url: &FeedUrl) -> Self { + Self(encode( + PODCAST_ID_PREFIX, + &digest(PODCAST_ID_DOMAIN, &[url.as_str().as_bytes()]), + )) + } +} + +/// Stable cross-device episode identity: `ep1:<52 lowercase base32 chars>`. +/// +/// Derived as `BLAKE3("furumi-podcast:episode:v1" || 0x00 || podcast_id || key)` +/// where `key` is the material of an [`EpisodeKey`]. Title, artwork or audio +/// URL changes never change the id of an existing episode. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)] +#[serde(try_from = "String", into = "String")] +pub struct EpisodeId(String); + +string_id!(EpisodeId, EPISODE_ID_PREFIX, "episode"); + +impl EpisodeId { + /// Derives an episode id from a key inside `podcast`. + pub fn derive(podcast: &PodcastId, key: &EpisodeKey) -> Self { + let material = key.material(); + Self(encode( + EPISODE_ID_PREFIX, + &digest( + EPISODE_ID_DOMAIN, + &[podcast.as_str().as_bytes(), material.as_bytes()], + ), + )) + } + + /// Derives the id of an episode with an RSS GUID (or Atom ``). + /// + /// Returns `None` when the GUID is blank or longer than [`MAX_GUID_BYTES`]. + pub fn from_guid(podcast: &PodcastId, guid: &str) -> Option { + EpisodeKey::guid(guid).map(|key| Self::derive(podcast, &key)) + } +} + +/// Key material from which an [`EpisodeId`] is derived. +/// +/// | Variant | Material | +/// | --- | --- | +/// | `Guid` | `guid:` + GUID trimmed of surrounding whitespace | +/// | `Link` | `link:` + `` trimmed | +/// | `DateTitle` | `date-title:` + unix seconds + `\0` + [`super::normalize_episode_title`] | +/// | `Enclosure` | `enclosure:` + enclosure URL trimmed | +/// +/// GUIDs and URLs are otherwise byte-for-byte: GUIDs are case-sensitive. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub enum EpisodeKey { + /// RSS `` or Atom ``. + Guid(String), + /// Item ``. + Link(String), + /// Publication time (whole unix seconds) and normalized title. + DateTitle { + /// Publication time in unix seconds. + published_at_secs: i64, + /// Title normalized by [`super::normalize_episode_title`]. + normalized_title: String, + }, + /// Enclosure (audio) URL. + Enclosure(String), +} + +impl EpisodeKey { + /// GUID key; `None` for a blank or oversized GUID. + pub fn guid(guid: &str) -> Option { + let guid = guid.trim(); + (!guid.is_empty() && guid.len() <= MAX_GUID_BYTES).then(|| Self::Guid(guid.to_string())) + } + + /// Link key; `None` for a blank or oversized link. + pub fn link(link: &str) -> Option { + let link = link.trim(); + (!link.is_empty() && link.len() <= super::MAX_URL_BYTES) + .then(|| Self::Link(link.to_string())) + } + + /// Date + title key; `None` when the title normalizes to nothing. + pub fn date_title(published_at_ms: i64, title: &str) -> Option { + let normalized_title = super::normalize_episode_title(title); + (!normalized_title.is_empty()).then(|| Self::DateTitle { + published_at_secs: published_at_ms.div_euclid(1_000), + normalized_title, + }) + } + + /// Enclosure key; `None` for a blank or oversized URL. + pub fn enclosure(url: &str) -> Option { + let url = url.trim(); + (!url.is_empty() && url.len() <= super::MAX_URL_BYTES) + .then(|| Self::Enclosure(url.to_string())) + } + + /// Exact bytes hashed after the podcast id. + pub fn material(&self) -> String { + match self { + Self::Guid(guid) => format!("guid:{guid}"), + Self::Link(link) => format!("link:{link}"), + Self::DateTitle { + published_at_secs, + normalized_title, + } => format!("date-title:{published_at_secs}\0{normalized_title}"), + Self::Enclosure(url) => format!("enclosure:{url}"), + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn podcast() -> PodcastId { + PodcastId::from_feed_url(&FeedUrl::parse("https://example.test/feed.xml").unwrap()) + } + + #[test] + fn podcast_id_is_domain_separated_blake3() { + let url = FeedUrl::parse("https://example.test/feed.xml").unwrap(); + let mut input = b"furumi-podcast:podcast:v1\0".to_vec(); + input.extend_from_slice(url.as_str().as_bytes()); + let expected = blake3::hash(&input); + let id = PodcastId::from_feed_url(&url); + assert_eq!(&id.digest(), expected.as_bytes()); + assert_eq!(id.as_str().len(), PODCAST_ID_PREFIX.len() + DIGEST_CHARS); + assert!(id.as_str()[5..].bytes().all(|b| !b.is_ascii_uppercase())); + } + + #[test] + fn podcast_id_golden_value() { + // Golden vector: changing it breaks every stored and synced id. + let id = podcast(); + let mut input = b"furumi-podcast:podcast:v1\0".to_vec(); + input.extend_from_slice(b"https://example.test/feed.xml"); + let mut body = data_encoding::BASE32_NOPAD.encode(blake3::hash(&input).as_bytes()); + body.make_ascii_lowercase(); + assert_eq!(id.as_str(), format!("pod1:{body}")); + } + + #[test] + fn episode_id_follows_the_plan_formula() { + let podcast = podcast(); + let id = EpisodeId::from_guid(&podcast, " abc-123 ").unwrap(); + let mut input = b"furumi-podcast:episode:v1\0".to_vec(); + input.extend_from_slice(podcast.as_str().as_bytes()); + input.extend_from_slice(b"guid:abc-123"); + assert_eq!(&id.digest(), blake3::hash(&input).as_bytes()); + // GUIDs are case-sensitive and podcast-scoped. + assert_ne!(EpisodeId::from_guid(&podcast, "ABC-123"), Some(id.clone())); + let other = PodcastId::from_feed_url(&FeedUrl::parse("https://other.test/").unwrap()); + assert_ne!(EpisodeId::from_guid(&other, "abc-123"), Some(id)); + } + + #[test] + fn keys_are_distinct_per_kind() { + let podcast = podcast(); + let value = "https://example.test/e1"; + let link = EpisodeId::derive(&podcast, &EpisodeKey::link(value).unwrap()); + let guid = EpisodeId::derive(&podcast, &EpisodeKey::guid(value).unwrap()); + let enclosure = EpisodeId::derive(&podcast, &EpisodeKey::enclosure(value).unwrap()); + assert_ne!(link, guid); + assert_ne!(link, enclosure); + assert_ne!(guid, enclosure); + } + + #[test] + fn blank_and_oversized_keys_are_rejected() { + assert!(EpisodeKey::guid(" ").is_none()); + assert!(EpisodeKey::guid(&"g".repeat(MAX_GUID_BYTES)).is_some()); + assert!(EpisodeKey::guid(&"g".repeat(MAX_GUID_BYTES + 1)).is_none()); + assert!(EpisodeKey::date_title(0, " -- ").is_none()); + assert!(EpisodeKey::link("").is_none()); + } + + #[test] + fn date_title_uses_whole_seconds_and_normalized_title() { + let a = EpisodeKey::date_title(1_700_000_000_123, "Hello, World!").unwrap(); + let b = EpisodeKey::date_title(1_700_000_000_999, "hello world").unwrap(); + assert_eq!(a, b); + let c = EpisodeKey::date_title(-1, "x").unwrap(); + assert_eq!( + c, + EpisodeKey::DateTitle { + published_at_secs: -1, + normalized_title: "x".to_string() + } + ); + } + + #[test] + fn parsing_validates_and_round_trips() { + let id = podcast(); + assert_eq!(PodcastId::parse(id.as_str()).unwrap(), id); + let json = serde_json::to_string(&id).unwrap(); + assert_eq!(serde_json::from_str::(&json).unwrap(), id); + + let upper = id.as_str().to_ascii_uppercase().replace("POD1:", "pod1:"); + assert!(PodcastId::parse(&upper).is_err()); + assert!(PodcastId::parse(&id.as_str()[..id.as_str().len() - 1]).is_err()); + assert!(PodcastId::parse(&format!("{id}a")).is_err()); + assert!(PodcastId::parse("pod1:").is_err()); + assert!(PodcastId::parse("").is_err()); + assert!(EpisodeId::parse(id.as_str()).is_err()); + assert!(serde_json::from_str::("\"pod1:xyz\"").is_err()); + + // Non-canonical trailing bits: last char encodes 1 data bit + 4 zero bits. + let mut chars: Vec = id.as_str().chars().collect(); + let last = chars.len() - 1; + chars[last] = if chars[last] == 'b' { 'c' } else { 'b' }; + let tampered: String = chars.into_iter().collect(); + assert!(PodcastId::parse(&tampered).is_err()); + } +} diff --git a/crates/music-dht/src/podcast/identity.rs b/crates/music-dht/src/podcast/identity.rs new file mode 100644 index 0000000..af91112 --- /dev/null +++ b/crates/music-dht/src/podcast/identity.rs @@ -0,0 +1,512 @@ +//! Episode identity resolution, including the documented no-GUID rule. + +use std::collections::{BTreeMap, BTreeSet}; + +use serde::{Deserialize, Serialize}; + +use super::{EpisodeId, EpisodeKey, PodcastId}; + +/// Normalizes an episode title for the `(date, title)` identity key. +/// +/// This is [`crate::normalize_name`]: NFKC, lowercase, non-alphanumeric runs +/// collapsed to one space, trimmed. It is part of the episode-id derivation. +pub fn normalize_episode_title(title: &str) -> String { + crate::normalize_name(title) +} + +/// Fields of a feed item (or of a stored episode) that identify it. +/// +/// The parser in `podcast::feed` produces these hints; stores keep them for +/// known episodes so that a later refresh can recognize items without GUID. +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] +pub struct EpisodeIdentityHints { + /// RSS `` / Atom ``, when present. + #[serde(default)] + pub guid: Option, + /// Enclosure (audio) URL. + #[serde(default)] + pub enclosure_url: Option, + /// Item ``. + #[serde(default)] + pub link: Option, + /// Publication time in unix milliseconds. + #[serde(default)] + pub published_at_ms: Option, + /// Item title. + #[serde(default)] + pub title: Option, +} + +impl EpisodeIdentityHints { + fn guid_key(&self) -> Option { + self.guid.as_deref().and_then(EpisodeKey::guid) + } + + fn enclosure(&self) -> Option<&str> { + trimmed(self.enclosure_url.as_deref()) + } + + fn link(&self) -> Option<&str> { + trimmed(self.link.as_deref()) + } + + fn date_title(&self) -> Option<(i64, String)> { + let published = self.published_at_ms?.div_euclid(1_000); + let title = normalize_episode_title(self.title.as_deref()?); + (!title.is_empty()).then_some((published, title)) + } +} + +struct Usable<'a> { + link: Option<&'a str>, + enclosure: Option<&'a str>, + date_title: Option<(i64, String)>, +} + +fn trimmed(value: Option<&str>) -> Option<&str> { + value.map(str::trim).filter(|value| !value.is_empty()) +} + +/// An episode already stored for the podcast, with the hints it was last seen with. +/// +/// Include episodes learned through sync (progress operations, queue items) +/// as well as episodes from earlier RSS refreshes. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct KnownEpisode { + /// Existing stable id. + pub episode_id: EpisodeId, + /// Identity hints recorded for it. + pub hints: EpisodeIdentityHints, +} + +/// Resolves the id of a single feed item. See [`resolve_episode_ids`]. +/// +/// A single item has no feed context, so its `` is only used when it +/// differs from `channel_link`. Prefer [`resolve_episode_ids`] for a whole +/// feed refresh. +pub fn resolve_episode_id( + podcast: &PodcastId, + channel_link: Option<&str>, + item: &EpisodeIdentityHints, + known: &[KnownEpisode], +) -> Option { + resolve_episode_ids(podcast, channel_link, std::slice::from_ref(item), known) + .pop() + .flatten() +} + +/// Resolves stable ids for the items of one feed document. +/// +/// Returns one entry per item, in order; `None` marks an item that cannot be +/// identified (no usable key) or that duplicates an earlier item of the same +/// document. The rule (normative, see `PODCASTS.md`): +/// +/// 1. An item with a GUID gets `EpisodeId::from_guid`. A GUID never matches +/// a different known episode, so the id is independent of local history. +/// 2. An item without a GUID first looks for a known episode, in this order: +/// same enclosure URL, then same ``, then same publication second and +/// [`normalize_episode_title`]. The first stage with candidates wins; among +/// candidates the smallest id is reused. A known episode already claimed by +/// another item of this document is not a candidate. +/// 3. Otherwise a new id is derived from the first available key: ``, +/// then `(date, title)`, then enclosure URL. +/// +/// A `` is only identifying when it is unique within the document and +/// differs from the channel link; many feeds repeat the show homepage in every +/// item. The same applies to enclosure URLs and `(date, title)` pairs shared +/// by several GUID-less items. +pub fn resolve_episode_ids( + podcast: &PodcastId, + channel_link: Option<&str>, + items: &[EpisodeIdentityHints], + known: &[KnownEpisode], +) -> Vec> { + let channel_link = trimmed(channel_link); + let mut link_counts: BTreeMap<&str, usize> = BTreeMap::new(); + let mut enclosure_counts: BTreeMap<&str, usize> = BTreeMap::new(); + let mut date_title_counts: BTreeMap<(i64, String), usize> = BTreeMap::new(); + for item in items { + if let Some(link) = item.link() { + *link_counts.entry(link).or_default() += 1; + } + if item.guid_key().is_none() { + if let Some(url) = item.enclosure() { + *enclosure_counts.entry(url).or_default() += 1; + } + if let Some(pair) = item.date_title() { + *date_title_counts.entry(pair).or_default() += 1; + } + } + } + let usable: Vec> = items + .iter() + .map(|item| Usable { + link: item + .link() + .filter(|link| Some(*link) != channel_link && link_counts.get(link) == Some(&1)), + enclosure: item + .enclosure() + .filter(|url| enclosure_counts.get(url) == Some(&1)), + date_title: item + .date_title() + .filter(|pair| date_title_counts.get(pair) == Some(&1)), + }) + .collect(); + + let mut claimed: BTreeSet = BTreeSet::new(); + let mut out: Vec> = vec![None; items.len()]; + + // Pass 1: GUID items claim their derived ids first. + for (index, item) in items.iter().enumerate() { + if let Some(key) = item.guid_key() { + let id = EpisodeId::derive(podcast, &key); + if claimed.insert(id.clone()) { + out[index] = Some(id); + } + } + } + + // Pass 2: GUID-less items reuse a matching known episode. + let mut pending = Vec::new(); + for (index, item) in items.iter().enumerate() { + if item.guid_key().is_some() { + continue; + } + let own = &usable[index]; + let stages: [&dyn Fn(&EpisodeIdentityHints) -> bool; 3] = [ + &|candidate| { + own.enclosure + .is_some_and(|url| candidate.enclosure() == Some(url)) + }, + &|candidate| own.link.is_some_and(|link| candidate.link() == Some(link)), + &|candidate| { + own.date_title + .as_ref() + .is_some_and(|pair| candidate.date_title().as_ref() == Some(pair)) + }, + ]; + let reused = stages.iter().find_map(|matches| { + known + .iter() + .filter(|known| !claimed.contains(&known.episode_id) && matches(&known.hints)) + .map(|known| &known.episode_id) + .min() + .cloned() + }); + match reused { + Some(id) => { + claimed.insert(id.clone()); + out[index] = Some(id); + } + None => pending.push(index), + } + } + + // Pass 3: derive new ids from the first available fallback key. + for index in pending { + let own = &usable[index]; + let key = own + .link + .and_then(EpisodeKey::link) + .or_else(|| { + own.date_title + .as_ref() + .map(|(secs, title)| EpisodeKey::DateTitle { + published_at_secs: *secs, + normalized_title: title.clone(), + }) + }) + .or_else(|| own.enclosure.and_then(EpisodeKey::enclosure)); + if let Some(key) = key { + let id = EpisodeId::derive(podcast, &key); + if claimed.insert(id.clone()) { + out[index] = Some(id); + } + } + } + out +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::podcast::FeedUrl; + + fn podcast() -> PodcastId { + PodcastId::from_feed_url(&FeedUrl::parse("https://example.test/feed").unwrap()) + } + + fn hints( + guid: Option<&str>, + enclosure: Option<&str>, + link: Option<&str>, + date: Option, + title: Option<&str>, + ) -> EpisodeIdentityHints { + EpisodeIdentityHints { + guid: guid.map(str::to_string), + enclosure_url: enclosure.map(str::to_string), + link: link.map(str::to_string), + published_at_ms: date, + title: title.map(str::to_string), + } + } + + fn derived(key: EpisodeKey) -> Option { + Some(EpisodeId::derive(&podcast(), &key)) + } + + #[test] + fn guid_wins_and_ignores_history() { + let item = hints(Some("g1"), Some("https://cdn/1.mp3"), None, None, Some("T")); + let known = [KnownEpisode { + episode_id: EpisodeId::from_guid(&podcast(), "other").unwrap(), + hints: hints(None, Some("https://cdn/1.mp3"), None, None, None), + }]; + assert_eq!( + resolve_episode_id(&podcast(), None, &item, &known), + derived(EpisodeKey::guid("g1").unwrap()) + ); + } + + #[test] + fn title_cover_and_audio_url_changes_keep_the_guid_id() { + let before = hints( + Some("g1"), + Some("https://cdn/a.mp3"), + None, + Some(1), + Some("Old"), + ); + let after = hints( + Some("g1"), + Some("https://cdn/b.mp3"), + None, + Some(2), + Some("New"), + ); + assert_eq!( + resolve_episode_id(&podcast(), None, &before, &[]), + resolve_episode_id(&podcast(), None, &after, &[]) + ); + } + + #[test] + fn fallback_key_order_for_new_items() { + let p = podcast(); + let with_link = hints( + None, + Some("https://cdn/1.mp3"), + Some("https://e/1"), + Some(5_000), + Some("A"), + ); + assert_eq!( + resolve_episode_id(&p, None, &with_link, &[]), + derived(EpisodeKey::link("https://e/1").unwrap()) + ); + let date_title = hints( + None, + Some("https://cdn/1.mp3"), + None, + Some(5_000), + Some("A"), + ); + assert_eq!( + resolve_episode_id(&p, None, &date_title, &[]), + derived(EpisodeKey::date_title(5_000, "A").unwrap()) + ); + let enclosure_only = hints(None, Some("https://cdn/1.mp3"), None, None, Some("A")); + assert_eq!( + resolve_episode_id(&p, None, &enclosure_only, &[]), + derived(EpisodeKey::enclosure("https://cdn/1.mp3").unwrap()) + ); + assert_eq!( + resolve_episode_id(&p, None, &EpisodeIdentityHints::default(), &[]), + None + ); + } + + #[test] + fn guidless_episode_keeps_its_id_after_title_and_url_changes() { + let p = podcast(); + // First seen: no link, so the id comes from (date, title). + let first = hints( + None, + Some("https://cdn/a.mp3"), + None, + Some(9_000), + Some("Pilot"), + ); + let id = resolve_episode_id(&p, None, &first, &[]).unwrap(); + let known = [KnownEpisode { + episode_id: id.clone(), + hints: first.clone(), + }]; + // Title changed: matched by enclosure. + let retitled = hints( + None, + Some("https://cdn/a.mp3"), + None, + Some(9_000), + Some("Pilot (remastered)"), + ); + assert_eq!( + resolve_episode_id(&p, None, &retitled, &known), + Some(id.clone()) + ); + // Audio URL changed: matched by (date, title). + let moved = hints( + None, + Some("https://cdn2/a.mp3"), + None, + Some(9_999), + Some("PILOT!"), + ); + assert_eq!( + resolve_episode_id(&p, None, &moved, &known), + Some(id.clone()) + ); + // Link appeared later: the enclosure still matches first. + let linked = hints( + None, + Some("https://cdn/a.mp3"), + Some("https://e/pilot"), + None, + None, + ); + assert_eq!(resolve_episode_id(&p, None, &linked, &known), Some(id)); + } + + #[test] + fn shared_channel_links_are_not_identifying() { + let p = podcast(); + let home = "https://show.test/"; + let items = [ + hints(None, Some("https://cdn/1.mp3"), Some(home), None, None), + hints(None, Some("https://cdn/2.mp3"), Some(home), None, None), + ]; + let ids = resolve_episode_ids(&p, Some(home), &items, &[]); + assert_eq!( + ids[0], + derived(EpisodeKey::enclosure("https://cdn/1.mp3").unwrap()) + ); + assert_eq!( + ids[1], + derived(EpisodeKey::enclosure("https://cdn/2.mp3").unwrap()) + ); + // The same holds without the channel link: the link repeats. + assert_eq!(resolve_episode_ids(&p, None, &items, &[]), ids); + // A single item whose link equals the channel link. + assert_eq!(resolve_episode_id(&p, Some(home), &items[0], &[]), ids[0]); + } + + #[test] + fn duplicates_in_one_document_are_dropped() { + let p = podcast(); + let items = [ + hints(Some("g"), Some("https://cdn/1.mp3"), None, None, None), + hints(Some("g"), Some("https://cdn/2.mp3"), None, None, None), + hints(None, Some("https://cdn/3.mp3"), None, None, None), + hints(None, Some("https://cdn/3.mp3"), None, None, None), + ]; + let ids = resolve_episode_ids(&p, None, &items, &[]); + assert!(ids[0].is_some()); + assert_eq!(ids[1], None); + // The shared enclosure is not identifying: both GUID-less items have + // no usable key. + assert_eq!(ids[2], None); + assert_eq!(ids[3], None); + } + + #[test] + fn a_known_episode_is_claimed_once() { + let p = podcast(); + let known_id = derived(EpisodeKey::enclosure("https://cdn/old.mp3").unwrap()).unwrap(); + let known = [KnownEpisode { + episode_id: known_id.clone(), + hints: hints( + None, + Some("https://cdn/old.mp3"), + None, + Some(1_000), + Some("Same"), + ), + }]; + // Two new items both match by (date, title) only if unique; here + // they share it, so neither matches; the enclosure one matches. + let items = [ + hints( + None, + Some("https://cdn/x.mp3"), + None, + Some(1_000), + Some("Same"), + ), + hints( + None, + Some("https://cdn/old.mp3"), + None, + Some(1_000), + Some("Same"), + ), + ]; + let ids = resolve_episode_ids(&p, None, &items, &known); + assert_eq!(ids[1], Some(known_id.clone())); + assert_eq!( + ids[0], + derived(EpisodeKey::enclosure("https://cdn/x.mp3").unwrap()) + ); + assert_ne!(ids[0], ids[1]); + } + + #[test] + fn ambiguous_known_matches_pick_the_smallest_id_in_any_order() { + let p = podcast(); + let a = EpisodeId::from_guid(&p, "a").unwrap(); + let b = EpisodeId::from_guid(&p, "b").unwrap(); + let same = hints(None, Some("https://cdn/1.mp3"), None, None, None); + let k1 = KnownEpisode { + episode_id: a.clone(), + hints: same.clone(), + }; + let k2 = KnownEpisode { + episode_id: b.clone(), + hints: same.clone(), + }; + let expected = Some(a.clone().min(b.clone())); + assert_eq!( + resolve_episode_id(&p, None, &same, &[k1.clone(), k2.clone()]), + expected + ); + assert_eq!(resolve_episode_id(&p, None, &same, &[k2, k1]), expected); + } + + #[test] + fn result_is_independent_of_known_order() { + let p = podcast(); + let items: Vec = (0..6) + .map(|i| { + hints( + None, + Some(&format!("https://cdn/{i}.mp3")), + Some(&format!("https://e/{i}")), + Some(i * 1_000), + Some(&format!("Ep {i}")), + ) + }) + .collect(); + let mut known: Vec = items + .iter() + .enumerate() + .map(|(i, h)| KnownEpisode { + episode_id: EpisodeId::from_guid(&p, &format!("legacy-{i}")).unwrap(), + hints: h.clone(), + }) + .collect(); + let forward = resolve_episode_ids(&p, None, &items, &known); + known.reverse(); + assert_eq!(resolve_episode_ids(&p, None, &items, &known), forward); + assert!(forward.iter().all(Option::is_some)); + } +} diff --git a/crates/music-dht/src/podcast/meta.rs b/crates/music-dht/src/podcast/meta.rs new file mode 100644 index 0000000..1f36ff7 --- /dev/null +++ b/crates/music-dht/src/podcast/meta.rs @@ -0,0 +1,480 @@ +//! Podcast and episode metadata DTOs. + +use serde::{Deserialize, Serialize}; + +use super::{ + EpisodeId, EpisodeIdentityHints, FeedUrl, MAX_DESCRIPTION_CHARS, MAX_GUID_BYTES, + MAX_MIME_BYTES, MAX_TITLE_CHARS, MAX_URL_BYTES, PodcastError, PodcastId, PodcastResult, + bounded_text, check_opt_text, check_opt_url, check_text, check_url, +}; + +/// `itunes:episodeType`. +/// +/// Unknown values deserialize (and parse) as [`EpisodeType::Full`], the +/// iTunes default, so publishers cannot break the wire format. +#[derive( + Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, +)] +#[serde(rename_all = "snake_case", from = "String")] +pub enum EpisodeType { + /// Regular episode. + #[default] + Full, + /// Trailer or teaser. + Trailer, + /// Bonus content. + Bonus, +} + +impl EpisodeType { + /// Parses an `itunes:episodeType` value, case-insensitively. + pub fn parse(value: &str) -> Self { + match value.trim().to_ascii_lowercase().as_str() { + "trailer" => Self::Trailer, + "bonus" => Self::Bonus, + _ => Self::Full, + } + } +} + +impl From for EpisodeType { + fn from(value: String) -> Self { + Self::parse(&value) + } +} + +/// Channel metadata of a podcast, as last fetched from its feed. +/// +/// Synced inside subscription operations so that another trusted device can +/// show and refresh the podcast without the user typing the URL again. It is +/// private user data: never publish it outside the trusted-device group. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)] +pub struct PodcastMeta { + /// Canonical URL the feed is currently fetched from. + pub feed_url: FeedUrl, + /// Podcast title. + pub title: String, + /// Author. + #[serde(default)] + pub author: Option, + /// Plain-text description, at most [`MAX_DESCRIPTION_CHARS`]. + #[serde(default)] + pub description: Option, + /// Publisher web page. + #[serde(default)] + pub link: Option, + /// Artwork URL. + #[serde(default)] + pub image_url: Option, +} + +impl PodcastMeta { + /// Validates contract bounds. + pub fn validate(&self) -> PodcastResult<()> { + check_text("podcast title", &self.title, MAX_TITLE_CHARS, true)?; + check_opt_text("podcast author", self.author.as_deref(), MAX_TITLE_CHARS)?; + check_opt_text( + "podcast description", + self.description.as_deref(), + MAX_DESCRIPTION_CHARS, + )?; + if self + .link + .as_ref() + .is_some_and(|link| link.len() > MAX_URL_BYTES) + { + return Err(PodcastError::InvalidField { + field: "podcast link", + reason: "is too long", + }); + } + check_opt_url("podcast image_url", self.image_url.as_deref()) + } + + /// Returns a copy that fits the contract bounds. + /// + /// Text is truncated with [`bounded_text`]; invalid optional URLs are + /// dropped; an empty title becomes `"Untitled podcast"`. + pub fn bounded(&self) -> Self { + Self { + feed_url: self.feed_url.clone(), + title: bounded_title(&self.title, "Untitled podcast"), + author: bounded_opt(self.author.as_deref(), MAX_TITLE_CHARS), + description: bounded_opt(self.description.as_deref(), MAX_DESCRIPTION_CHARS), + link: self + .link + .clone() + .filter(|link| link.len() <= MAX_URL_BYTES && !link.trim().is_empty()), + image_url: valid_url(self.image_url.as_deref()), + } + } +} + +/// Full episode metadata, as stored by clients and refreshed from RSS. +/// +/// Publisher metadata never touches personal progress or history: those are +/// separate records keyed by [`EpisodeId`]. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct EpisodeMeta { + /// Stable episode id. + pub episode_id: EpisodeId, + /// Owning podcast. + pub podcast_id: PodcastId, + /// RSS GUID / Atom id, when present. + #[serde(default)] + pub guid: Option, + /// Episode title. + pub title: String, + /// Plain-text description, at most [`MAX_DESCRIPTION_CHARS`]. + #[serde(default)] + pub description: Option, + /// `itunes:season`. Episodes without a season form their own group. + #[serde(default)] + pub season: Option, + /// `itunes:episode`. + #[serde(default)] + pub episode_number: Option, + /// `itunes:episodeType`. + #[serde(default)] + pub episode_type: EpisodeType, + /// Publication time in unix milliseconds. + #[serde(default)] + pub published_at_ms: Option, + /// Duration announced by the publisher, in milliseconds. + #[serde(default)] + pub duration_ms: Option, + /// Absolute http(s) audio URL at the publisher. + pub audio_url: String, + /// Enclosure MIME type. + #[serde(default)] + pub mime: Option, + /// Enclosure length in bytes. + #[serde(default)] + pub byte_len: Option, + /// Episode artwork URL. + #[serde(default)] + pub image_url: Option, + /// Episode web page. + #[serde(default)] + pub link: Option, +} + +impl EpisodeMeta { + /// Validates contract bounds. + pub fn validate(&self) -> PodcastResult<()> { + if self + .guid + .as_ref() + .is_some_and(|guid| guid.len() > MAX_GUID_BYTES) + { + return Err(PodcastError::InvalidField { + field: "episode guid", + reason: "is too long", + }); + } + check_text("episode title", &self.title, MAX_TITLE_CHARS, true)?; + check_opt_text( + "episode description", + self.description.as_deref(), + MAX_DESCRIPTION_CHARS, + )?; + check_duration(self.duration_ms)?; + check_url("episode audio_url", &self.audio_url)?; + check_mime(self.mime.as_deref())?; + check_opt_url("episode image_url", self.image_url.as_deref())?; + if self + .link + .as_ref() + .is_some_and(|link| link.len() > MAX_URL_BYTES) + { + return Err(PodcastError::InvalidField { + field: "episode link", + reason: "is too long", + }); + } + Ok(()) + } + + /// Identity hints to keep for the no-GUID matching rule. + pub fn identity_hints(&self) -> EpisodeIdentityHints { + EpisodeIdentityHints { + guid: self.guid.clone(), + enclosure_url: Some(self.audio_url.clone()), + link: self.link.clone(), + published_at_ms: self.published_at_ms, + title: Some(self.title.clone()), + } + } + + /// Builds the self-contained queue reference for this episode. + /// + /// The episode artwork falls back to the podcast artwork. + pub fn to_ref(&self, podcast: &PodcastMeta) -> PodcastEpisodeRef { + PodcastEpisodeRef { + podcast_id: self.podcast_id.clone(), + episode_id: self.episode_id.clone(), + feed_url: podcast.feed_url.clone(), + podcast_title: bounded_title(&podcast.title, "Untitled podcast"), + episode_title: bounded_title(&self.title, "Untitled episode"), + audio_url: self.audio_url.clone(), + mime: self + .mime + .clone() + .filter(|mime| check_mime(Some(mime)).is_ok()), + duration_ms: self.duration_ms.filter(|ms| *ms > 0), + published_at_ms: self.published_at_ms, + season: self.season, + episode_number: self.episode_number, + image_url: valid_url(self.image_url.as_deref()) + .or_else(|| valid_url(podcast.image_url.as_deref())), + } + } +} + +/// Self-contained, bounded reference to a podcast episode. +/// +/// Carried by playback queues (`PlaybackSource::PodcastEpisode`) and by +/// progress operations, so a receiving trusted device can display, resume and +/// play the episode without being subscribed and without its own copy of the +/// feed. It contains no personal state. It is private: Jam snapshots replace it +/// with an opaque placeholder. +/// +/// If the audio URL went stale, refresh the feed at `feed_url` and look the +/// episode up by `episode_id`. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct PodcastEpisodeRef { + /// Owning podcast. + pub podcast_id: PodcastId, + /// Episode. + pub episode_id: EpisodeId, + /// Canonical feed URL used to refresh the episode. + pub feed_url: FeedUrl, + /// Podcast title for display. + pub podcast_title: String, + /// Episode title for display. + pub episode_title: String, + /// Absolute http(s) audio URL at the publisher. + pub audio_url: String, + /// Enclosure MIME type. + #[serde(default)] + pub mime: Option, + /// Announced duration in milliseconds. + #[serde(default)] + pub duration_ms: Option, + /// Publication time in unix milliseconds. + #[serde(default)] + pub published_at_ms: Option, + /// `itunes:season`. + #[serde(default)] + pub season: Option, + /// `itunes:episode`. + #[serde(default)] + pub episode_number: Option, + /// Episode or podcast artwork URL. + #[serde(default)] + pub image_url: Option, +} + +impl PodcastEpisodeRef { + /// Validates contract bounds. Receivers must drop invalid references. + pub fn validate(&self) -> PodcastResult<()> { + check_text("podcast title", &self.podcast_title, MAX_TITLE_CHARS, true)?; + check_text("episode title", &self.episode_title, MAX_TITLE_CHARS, true)?; + check_url("episode audio_url", &self.audio_url)?; + check_mime(self.mime.as_deref())?; + check_duration(self.duration_ms)?; + check_opt_url("episode image_url", self.image_url.as_deref()) + } + + /// Identity hints known from this reference. + /// + /// Add them to the known-episode set before resolving ids from a feed so + /// a GUID-less episode learned through sync keeps its id. + pub fn identity_hints(&self) -> EpisodeIdentityHints { + EpisodeIdentityHints { + guid: None, + enclosure_url: Some(self.audio_url.clone()), + link: None, + published_at_ms: self.published_at_ms, + title: Some(self.episode_title.clone()), + } + } +} + +fn check_duration(duration_ms: Option) -> PodcastResult<()> { + if duration_ms.is_some_and(|ms| ms < 0) { + return Err(PodcastError::InvalidField { + field: "duration_ms", + reason: "must not be negative", + }); + } + Ok(()) +} + +fn check_mime(mime: Option<&str>) -> PodcastResult<()> { + let Some(mime) = mime else { return Ok(()) }; + if mime.is_empty() || mime.len() > MAX_MIME_BYTES || !mime.bytes().all(|b| b.is_ascii_graphic()) + { + return Err(PodcastError::InvalidField { + field: "mime", + reason: "must be a short printable ASCII token", + }); + } + Ok(()) +} + +fn bounded_title(title: &str, fallback: &str) -> String { + let title = title.trim(); + if title.is_empty() { + fallback.to_string() + } else { + bounded_text(title, MAX_TITLE_CHARS) + } +} + +fn bounded_opt(value: Option<&str>, max_chars: usize) -> Option { + value + .map(str::trim) + .filter(|value| !value.is_empty()) + .map(|value| bounded_text(value, max_chars)) +} + +fn valid_url(value: Option<&str>) -> Option { + value + .filter(|value| super::is_http_url(value)) + .map(str::to_string) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn podcast_meta() -> PodcastMeta { + PodcastMeta { + feed_url: FeedUrl::parse("https://example.test/feed").unwrap(), + title: "Show".to_string(), + author: Some("Host".to_string()), + description: None, + link: Some("https://example.test/".to_string()), + image_url: Some("https://example.test/cover.jpg".to_string()), + } + } + + fn episode() -> EpisodeMeta { + let podcast_id = PodcastId::from_feed_url(&podcast_meta().feed_url); + EpisodeMeta { + episode_id: EpisodeId::from_guid(&podcast_id, "g1").unwrap(), + podcast_id, + guid: Some("g1".to_string()), + title: "Pilot".to_string(), + description: Some("Notes".to_string()), + season: Some(2), + episode_number: Some(7), + episode_type: EpisodeType::Bonus, + published_at_ms: Some(1_700_000_000_000), + duration_ms: Some(3_600_000), + audio_url: "https://cdn.example.test/1.mp3?sig=abc".to_string(), + mime: Some("audio/mpeg".to_string()), + byte_len: Some(1234), + image_url: None, + link: Some("https://example.test/1".to_string()), + } + } + + #[test] + fn episode_type_is_tolerant() { + assert_eq!(EpisodeType::parse(" Trailer "), EpisodeType::Trailer); + assert_eq!(EpisodeType::parse("BONUS"), EpisodeType::Bonus); + assert_eq!(EpisodeType::parse("full"), EpisodeType::Full); + assert_eq!(EpisodeType::parse("teaser"), EpisodeType::Full); + assert_eq!( + serde_json::to_string(&EpisodeType::Trailer).unwrap(), + "\"trailer\"" + ); + assert_eq!( + serde_json::from_str::("\"something-new\"").unwrap(), + EpisodeType::Full + ); + } + + #[test] + fn metadata_round_trips_and_validates() { + let episode = episode(); + episode.validate().unwrap(); + let json = serde_json::to_string(&episode).unwrap(); + assert_eq!(serde_json::from_str::(&json).unwrap(), episode); + podcast_meta().validate().unwrap(); + + let mut bad = episode.clone(); + bad.audio_url = "file:///tmp/x.mp3".to_string(); + assert!(bad.validate().is_err()); + let mut bad = episode.clone(); + bad.description = Some("x".repeat(MAX_DESCRIPTION_CHARS + 1)); + assert!(bad.validate().is_err()); + let mut bad = episode; + bad.mime = Some("audio/mpeg; codecs=\"mp3\"".to_string()); + assert!(bad.validate().is_err()); + } + + #[test] + fn minimal_legacy_json_uses_defaults() { + let episode = episode(); + let json = format!( + r#"{{"episode_id":"{}","podcast_id":"{}","title":"T","audio_url":"https://a.test/1.mp3"}}"#, + episode.episode_id, episode.podcast_id + ); + let parsed: EpisodeMeta = serde_json::from_str(&json).unwrap(); + assert_eq!(parsed.episode_type, EpisodeType::Full); + assert_eq!(parsed.season, None); + } + + #[test] + fn episode_ref_is_self_contained_and_bounded() { + let podcast = podcast_meta(); + let mut episode = episode(); + episode.title = "x".repeat(MAX_TITLE_CHARS + 10); + let reference = episode.to_ref(&podcast); + reference.validate().unwrap(); + assert_eq!(reference.episode_title.chars().count(), MAX_TITLE_CHARS); + assert_eq!(reference.podcast_title, "Show"); + assert_eq!( + reference.image_url.as_deref(), + Some("https://example.test/cover.jpg") + ); + assert_eq!(reference.feed_url, podcast.feed_url); + let json = serde_json::to_string(&reference).unwrap(); + assert!(!json.contains("description")); + assert_eq!( + serde_json::from_str::(&json).unwrap(), + reference + ); + + let mut bad = reference.clone(); + bad.episode_title = " ".to_string(); + assert!(bad.validate().is_err()); + let mut bad = reference.clone(); + bad.audio_url = "javascript:alert(1)".to_string(); + assert!(bad.validate().is_err()); + let mut bad = reference; + bad.duration_ms = Some(-1); + assert!(bad.validate().is_err()); + } + + #[test] + fn refs_reject_invalid_ids_on_deserialization() { + let json = r#"{"podcast_id":"pod1:bad","episode_id":"ep1:bad","feed_url":"https://a.test/","podcast_title":"P","episode_title":"E","audio_url":"https://a.test/1.mp3"}"#; + assert!(serde_json::from_str::(json).is_err()); + } + + #[test] + fn bounded_podcast_meta_fits_the_contract() { + let mut meta = podcast_meta(); + meta.title = " ".to_string(); + meta.description = Some("d".repeat(MAX_DESCRIPTION_CHARS * 2)); + meta.image_url = Some("ftp://x".to_string()); + let bounded = meta.bounded(); + bounded.validate().unwrap(); + assert_eq!(bounded.title, "Untitled podcast"); + assert_eq!(bounded.image_url, None); + } +} diff --git a/crates/music-dht/src/podcast/mod.rs b/crates/music-dht/src/podcast/mod.rs new file mode 100644 index 0000000..a9d6e43 --- /dev/null +++ b/crates/music-dht/src/podcast/mod.rs @@ -0,0 +1,298 @@ +//! 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, `` +//! or (date, normalized title) and only then derives a new id from the +//! first available fallback key. +//! +//! # Personal state +//! +//! * [`SubscriptionRecord`]: last-writer-wins by `(hlc_ms, op_id)`; +//! unsubscribing is state, not a tombstone. Feed aliases merge as a bounded +//! grow-only set. +//! * [`ShareRecord`]: last-writer-wins; `shared = false` is a tombstone. 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. +//! +//! ``` +//! 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; + +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, 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 = std::result::Result; + +/// 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)); + } +} diff --git a/crates/music-dht/src/podcast/state.rs b/crates/music-dht/src/podcast/state.rs new file mode 100644 index 0000000..c258eb7 --- /dev/null +++ b/crates/music-dht/src/podcast/state.rs @@ -0,0 +1,445 @@ +//! Personal podcast state and its convergent merge rules. +//! +//! Every merge function here is commutative, associative and idempotent over +//! records of the same entity, so trusted devices that receive the same set of +//! operations converge to the same state regardless of delivery order and +//! duplication. All ties are broken by a total order over every field. + +use std::cmp::Ordering; +use std::collections::BTreeSet; + +use serde::{Deserialize, Serialize}; + +use super::{ + EpisodeId, FeedUrl, MAX_FEED_ALIASES, PodcastError, PodcastId, PodcastMeta, PodcastResult, + check_token, merge_feed_aliases, +}; + +/// Largest tail of an episode that still counts as finished, in milliseconds. +/// +/// See [`reaches_completion`]. +pub const COMPLETION_TAIL_MAX_MS: i64 = 30_000; + +/// Minimum actual listening time for a non-completed session to enter history. +pub const MIN_RECORDED_EPISODE_LISTEN_MS: i64 = 30_000; + +/// Shared automatic completion criterion for every client. +/// +/// A position completes an episode when it is within the smaller of 30 s and +/// 5 % of the duration from the end. Natural end of stream always completes, +/// whatever the announced duration. Without a known positive duration only the +/// end of stream completes. +pub fn reaches_completion(position_ms: i64, duration_ms: Option) -> bool { + let Some(duration) = duration_ms.filter(|duration| *duration > 0) else { + return false; + }; + let tail = COMPLETION_TAIL_MAX_MS.min(duration / 20); + position_ms >= duration - tail +} + +/// Listening status of one episode. +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum ProgressStatus { + /// Never started, or explicitly marked unplayed. + NotStarted, + /// Started and not finished. + InProgress, + /// Finished, automatically or by an explicit "mark played". + Completed, +} + +/// Durable resume register of one episode. +/// +/// The winner among records of the same episode is the greatest +/// `(generation, hlc_ms, device_id, op_id)`; remaining fields only break ties +/// between malformed duplicates. Progress is **never** the maximum position: +/// seeking backwards and "start over" are real changes. +/// +/// * Explicit user actions (start of a new listening session, seek, "start +/// over", "mark played", "mark unplayed", handoff to another device) use +/// [`ProgressRecord::explicit_generation`]: one more than the greatest +/// generation the device has seen for the episode. This is a Lamport clock, +/// so wall-clock skew cannot undo an explicit action that was observed. +/// * Periodic checkpoints keep the generation of the latest explicit action of +/// their session. A late checkpoint of an older session therefore loses +/// against any newer explicit action, whatever its `hlc_ms`. +/// * Concurrent explicit actions on offline devices receive the same +/// generation and are ordered by `hlc_ms`, then `device_id`, then `op_id`. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct ProgressRecord { + /// Episode the register belongs to. + pub episode_id: EpisodeId, + /// Owning podcast. + pub podcast_id: PodcastId, + /// Resume position in milliseconds. + pub position_ms: i64, + /// Listening status. + pub status: ProgressStatus, + /// Lamport generation of the latest explicit action (see type docs). + pub generation: u64, + /// Listening session (or explicit action) that wrote the record. + pub session_id: String, + /// Logical write time, normally the sync operation `hlc_ms`. + pub hlc_ms: i64, + /// Writing device, normally the sync operation origin. + pub device_id: String, + /// Writing operation id. + pub op_id: String, +} + +impl ProgressRecord { + /// Generation for an explicit user action, given the greatest generation + /// already seen for the episode (`None` when none was seen). + pub fn explicit_generation(max_seen: Option) -> u64 { + max_seen.map_or(1, |generation| generation.saturating_add(1)) + } + + /// Primary ordering key. + pub fn order_key(&self) -> (u64, i64, &str, &str) { + ( + self.generation, + self.hlc_ms, + self.device_id.as_str(), + self.op_id.as_str(), + ) + } + + fn total_cmp(&self, other: &Self) -> Ordering { + self.order_key() + .cmp(&other.order_key()) + .then_with(|| self.position_ms.cmp(&other.position_ms)) + .then_with(|| self.status.cmp(&other.status)) + .then_with(|| self.session_id.cmp(&other.session_id)) + .then_with(|| self.podcast_id.cmp(&other.podcast_id)) + } + + /// Returns whether this record wins over `other` (same episode). + pub fn supersedes(&self, other: &Self) -> bool { + self.total_cmp(other) == Ordering::Greater + } + + /// Position from which ordinary Play resumes. + /// + /// Completed and not-started episodes start from the beginning; use the + /// explicit "start over" action to restart an in-progress episode. + pub fn resume_position_ms(&self) -> i64 { + match self.status { + ProgressStatus::InProgress => self.position_ms, + ProgressStatus::NotStarted | ProgressStatus::Completed => 0, + } + } + + /// Validates contract bounds. + pub fn validate(&self) -> PodcastResult<()> { + if self.position_ms < 0 { + return Err(PodcastError::InvalidField { + field: "position_ms", + reason: "must not be negative", + }); + } + check_token("session_id", &self.session_id)?; + check_token("device_id", &self.device_id)?; + check_token("op_id", &self.op_id) + } +} + +/// Merges two progress registers of the same episode. +pub fn merge_progress( + current: &ProgressRecord, + incoming: &ProgressRecord, +) -> PodcastResult { + if current.episode_id != incoming.episode_id { + return Err(PodcastError::Mismatch("episodes")); + } + Ok(if incoming.supersedes(current) { + incoming.clone() + } else { + current.clone() + }) +} + +/// Personal subscription state of one podcast. +/// +/// `subscribed` and `podcast` form one last-writer-wins register ordered by +/// `(hlc_ms, op_id)`. Unsubscribing writes `subscribed = false`: it is state, +/// not a tombstone, and never deletes progress or history, so subscribing +/// again continues where the user stopped. +/// +/// Only explicit user actions (subscribe, unsubscribe) write this register. +/// Background RSS refreshes keep their metadata locally and must not emit a +/// subscription operation; otherwise a stale device could resurrect an +/// unsubscribed podcast. +/// +/// `feed_aliases` is a bounded grow-only set merged independently of the +/// register (see [`merge_feed_aliases`]); it always contains every +/// `podcast.feed_url` seen. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct SubscriptionRecord { + /// Podcast. + pub podcast_id: PodcastId, + /// Whether the user is subscribed. + pub subscribed: bool, + /// Channel metadata at the time of the write. + pub podcast: PodcastMeta, + /// Known feed URLs of the podcast. + #[serde(default)] + pub feed_aliases: Vec, + /// Logical write time. + pub hlc_ms: i64, + /// Writing operation id. + pub op_id: String, +} + +impl SubscriptionRecord { + fn total_cmp(&self, other: &Self) -> Ordering { + (self.hlc_ms, self.op_id.as_str()) + .cmp(&(other.hlc_ms, other.op_id.as_str())) + .then_with(|| self.subscribed.cmp(&other.subscribed)) + .then_with(|| self.podcast.cmp(&other.podcast)) + } + + /// Returns whether this record's register wins over `other`'s. + pub fn supersedes(&self, other: &Self) -> bool { + self.total_cmp(other) == Ordering::Greater + } + + /// Ensures `feed_aliases` is sorted, bounded and contains `podcast.feed_url`. + pub fn normalize(&mut self) { + self.feed_aliases = merge_feed_aliases( + &self.podcast_id, + &self.feed_aliases, + std::slice::from_ref(&self.podcast.feed_url), + ); + } + + /// Validates contract bounds. + pub fn validate(&self) -> PodcastResult<()> { + self.podcast.validate()?; + if self.feed_aliases.len() > MAX_FEED_ALIASES + 1 { + return Err(PodcastError::InvalidField { + field: "feed_aliases", + reason: "has too many entries", + }); + } + check_token("op_id", &self.op_id) + } +} + +/// Merges two subscription records of the same podcast. +/// +/// The result is normalized (see [`SubscriptionRecord::normalize`]). +pub fn merge_subscription( + current: &SubscriptionRecord, + incoming: &SubscriptionRecord, +) -> PodcastResult { + if current.podcast_id != incoming.podcast_id { + return Err(PodcastError::Mismatch("podcasts")); + } + let mut merged = if incoming.supersedes(current) { + incoming.clone() + } else { + current.clone() + }; + let mut left = current.feed_aliases.clone(); + left.push(current.podcast.feed_url.clone()); + let mut right = incoming.feed_aliases.clone(); + right.push(incoming.podcast.feed_url.clone()); + merged.feed_aliases = merge_feed_aliases(&merged.podcast_id, &left, &right); + Ok(merged) +} + +/// Decision to publish a podcast card to the federation. +/// +/// Last-writer-wins by `(hlc_ms, op_id)`; `shared = false` is the tombstone +/// that revokes the publication. Unsubscribing must also write +/// `shared = false`. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct ShareRecord { + /// Podcast. + pub podcast_id: PodcastId, + /// Whether the user chose to share the podcast. + pub shared: bool, + /// Logical write time. + pub hlc_ms: i64, + /// Writing operation id. + pub op_id: String, +} + +impl ShareRecord { + fn total_cmp(&self, other: &Self) -> Ordering { + (self.hlc_ms, self.op_id.as_str(), self.shared).cmp(&( + other.hlc_ms, + other.op_id.as_str(), + other.shared, + )) + } + + /// Returns whether this record wins over `other`. + pub fn supersedes(&self, other: &Self) -> bool { + self.total_cmp(other) == Ordering::Greater + } + + /// Validates contract bounds. + pub fn validate(&self) -> PodcastResult<()> { + check_token("op_id", &self.op_id) + } +} + +/// Merges two share records of the same podcast. +pub fn merge_share(current: &ShareRecord, incoming: &ShareRecord) -> PodcastResult { + if current.podcast_id != incoming.podcast_id { + return Err(PodcastError::Mismatch("podcasts")); + } + Ok(if incoming.supersedes(current) { + incoming.clone() + } else { + current.clone() + }) +} + +/// Whether a podcast must currently be published. +/// +/// True only when the user is subscribed, chose to share, and the share +/// decision is newer than the latest subscription write. A new subscription +/// (including re-subscribing, or subscribing from someone else's public card) +/// is therefore always private until the user shares it again, and a stale +/// device cannot republish a podcast through an old share decision. +pub fn effective_share( + subscription: Option<&SubscriptionRecord>, + share: Option<&ShareRecord>, +) -> bool { + match (subscription, share) { + (Some(subscription), Some(share)) => { + subscription.subscribed + && share.shared + && subscription.podcast_id == share.podcast_id + && (share.hlc_ms, share.op_id.as_str()) + > (subscription.hlc_ms, subscription.op_id.as_str()) + } + _ => false, + } +} + +/// One listening session of an episode on one device. +/// +/// Sessions form a grow-only set keyed by `session_id`, generated when +/// playback of the episode starts on a device. A device may re-send its +/// session with more listening time (for example after a crash); versions of +/// one session merge by [`merge_listen_session`]. +/// +/// * A session enters history when it completed or lasted at least +/// [`MIN_RECORDED_EPISODE_LISTEN_MS`] ([`ListenSession::should_record`]). +/// * `completed` is set when the session reached [`reaches_completion`] or the +/// natural end of the stream. Each session counts at most once, so the play +/// count of an episode is the number of distinct completed sessions +/// ([`completed_listen_count`]); duplicate delivery never double counts. +/// * "Mark played" changes [`ProgressRecord::status`] only. It does not create +/// a session and does not invent listening time. +/// * Sessions listened concurrently on offline devices are all kept. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct ListenSession { + /// Unique session id, normally a UUID. + pub session_id: String, + /// Episode. + pub episode_id: EpisodeId, + /// Owning podcast. + pub podcast_id: PodcastId, + /// Device that played the session. + pub device_id: String, + /// Session start in unix milliseconds. + pub started_at_ms: i64, + /// Latest update of the session in unix milliseconds. + pub ended_at_ms: i64, + /// Position when the session started. + pub start_position_ms: i64, + /// Position when the session ended (or was last reported). + pub end_position_ms: i64, + /// Actual accumulated listening time, excluding pauses and seeks. + pub listened_ms: i64, + /// Whether the session completed the episode. + pub completed: bool, +} + +impl ListenSession { + fn total_cmp(&self, other: &Self) -> Ordering { + ( + self.completed, + self.listened_ms, + self.ended_at_ms, + self.end_position_ms, + self.started_at_ms, + self.start_position_ms, + ) + .cmp(&( + other.completed, + other.listened_ms, + other.ended_at_ms, + other.end_position_ms, + other.started_at_ms, + other.start_position_ms, + )) + } + + /// Whether the session belongs in listening history. + pub fn should_record(&self) -> bool { + self.completed || self.listened_ms >= MIN_RECORDED_EPISODE_LISTEN_MS + } + + /// Validates contract bounds. + pub fn validate(&self) -> PodcastResult<()> { + check_token("session_id", &self.session_id)?; + check_token("device_id", &self.device_id)?; + if self.started_at_ms < 0 || self.ended_at_ms < self.started_at_ms { + return Err(PodcastError::InvalidField { + field: "ended_at_ms", + reason: "must not precede started_at_ms", + }); + } + if self.start_position_ms < 0 || self.end_position_ms < 0 || self.listened_ms < 0 { + return Err(PodcastError::InvalidField { + field: "listened_ms", + reason: "positions and listening time must not be negative", + }); + } + Ok(()) + } +} + +/// Merges two versions of the same listening session. +/// +/// The version with the greatest `(completed, listened_ms, ended_at_ms, ...)` +/// wins, so a session can only grow. +pub fn merge_listen_session( + current: &ListenSession, + incoming: &ListenSession, +) -> PodcastResult { + if current.session_id != incoming.session_id { + return Err(PodcastError::Mismatch("sessions")); + } + if current.episode_id != incoming.episode_id + || current.podcast_id != incoming.podcast_id + || current.device_id != incoming.device_id + { + return Err(PodcastError::Mismatch("session identities")); + } + Ok(if incoming.total_cmp(current) == Ordering::Greater { + incoming.clone() + } else { + current.clone() + }) +} + +/// Number of distinct sessions that completed an episode. +pub fn completed_listen_count<'a>(sessions: impl IntoIterator) -> usize { + sessions + .into_iter() + .filter(|session| session.completed) + .map(|session| session.session_id.as_str()) + .collect::>() + .len() +} + +#[cfg(test)] +#[path = "state_tests.rs"] +mod tests; diff --git a/crates/music-dht/src/podcast/state_tests.rs b/crates/music-dht/src/podcast/state_tests.rs new file mode 100644 index 0000000..2bbf60a --- /dev/null +++ b/crates/music-dht/src/podcast/state_tests.rs @@ -0,0 +1,568 @@ +use std::collections::BTreeMap; + +use super::*; +use crate::podcast::{EpisodeIdentityHints, EpisodeMeta, EpisodeType, resolve_episode_ids}; + +fn permutations(items: &[T]) -> Vec> { + if items.len() <= 1 { + return vec![items.to_vec()]; + } + let mut out = Vec::new(); + for index in 0..items.len() { + let mut rest = items.to_vec(); + let head = rest.remove(index); + for mut tail in permutations(&rest) { + tail.insert(0, head.clone()); + out.push(tail); + } + } + out +} + +fn feed_url(path: &str) -> FeedUrl { + FeedUrl::parse(&format!("https://example.test/{path}")).unwrap() +} + +fn podcast_id() -> PodcastId { + PodcastId::from_feed_url(&feed_url("feed")) +} + +fn episode_id(guid: &str) -> EpisodeId { + EpisodeId::from_guid(&podcast_id(), guid).unwrap() +} + +fn progress( + generation: u64, + hlc_ms: i64, + device: &str, + op: &str, + position_ms: i64, + status: ProgressStatus, + session: &str, +) -> ProgressRecord { + ProgressRecord { + episode_id: episode_id("e1"), + podcast_id: podcast_id(), + position_ms, + status, + generation, + session_id: session.to_string(), + hlc_ms, + device_id: device.to_string(), + op_id: op.to_string(), + } +} + +fn fold(items: &[T], merge: impl Fn(&T, &T) -> PodcastResult) -> T { + let mut iter = items.iter(); + let first = iter.next().expect("non-empty").clone(); + iter.fold(first, |acc, item| merge(&acc, item).unwrap()) +} + +fn assert_converges( + items: &[T], + merge: impl Fn(&T, &T) -> PodcastResult + Copy, +) -> T { + let reference = fold(items, merge); + for order in permutations(items) { + assert_eq!(fold(&order, merge), reference, "order: {order:?}"); + } + // Merge laws on every pair and triple. + for a in items { + assert_eq!( + merge(&merge(a, a).unwrap(), a).unwrap(), + merge(a, a).unwrap() + ); + for b in items { + assert_eq!(merge(a, b).unwrap(), merge(b, a).unwrap()); + for c in items { + assert_eq!( + merge(&merge(a, b).unwrap(), c).unwrap(), + merge(a, &merge(b, c).unwrap()).unwrap() + ); + } + } + } + reference +} + +#[test] +fn progress_converges_for_every_permutation() { + use ProgressStatus::*; + let ops = [ + progress(1, 100, "dev-a", "dev-a:1", 10_000, InProgress, "s1"), + progress(1, 160, "dev-a", "dev-a:2", 70_000, InProgress, "s1"), + progress(2, 150, "dev-b", "dev-b:1", 0, InProgress, "s2"), + progress(2, 150, "dev-c", "dev-c:1", 5_000, InProgress, "s3"), + progress(2, 140, "dev-b", "dev-b:2", 0, Completed, "s2"), + // Duplicate delivery of the same operation. + progress(1, 160, "dev-a", "dev-a:2", 70_000, InProgress, "s1"), + ]; + let winner = assert_converges(&ops, merge_progress); + assert_eq!(winner.op_id, "dev-c:1"); +} + +#[test] +fn late_old_generation_checkpoint_loses() { + use ProgressStatus::*; + // Device A keeps checkpointing session s1 (generation 3) with a clock far + // ahead; device B explicitly seeks back (generation 4) with a slow clock. + let seek_back = progress(4, 1_000, "dev-b", "dev-b:9", 60_000, InProgress, "s2"); + let late = progress( + 3, 9_000_000, "dev-a", "dev-a:50", 3_000_000, InProgress, "s1", + ); + for order in [[&seek_back, &late], [&late, &seek_back]] { + let merged = merge_progress(order[0], order[1]).unwrap(); + assert_eq!(merged, seek_back); + } + assert!(seek_back.supersedes(&late)); + assert!(!late.supersedes(&seek_back)); +} + +#[test] +fn restart_beats_later_checkpoint_of_the_old_session() { + use ProgressStatus::*; + let checkpoint = progress(2, 100, "dev-a", "dev-a:1", 2_400_000, InProgress, "s1"); + let generation = ProgressRecord::explicit_generation(Some(checkpoint.generation)); + assert_eq!(generation, 3); + let restart = progress(generation, 110, "dev-a", "dev-a:2", 0, InProgress, "s2"); + // A checkpoint of s1 that was queued before the restart and delivered + // later, even stamped after the restart. + let late = progress(2, 120, "dev-a", "dev-a:3", 2_460_000, InProgress, "s1"); + let merged = assert_converges(&[checkpoint, restart.clone(), late], merge_progress); + assert_eq!(merged, restart); + assert_eq!(merged.resume_position_ms(), 0); +} + +#[test] +fn progress_is_not_the_maximum_position() { + use ProgressStatus::*; + let ahead = progress(1, 100, "dev-a", "dev-a:1", 3_000_000, InProgress, "s1"); + let back = progress(2, 101, "dev-a", "dev-a:2", 60_000, InProgress, "s1"); + assert_eq!(merge_progress(&ahead, &back).unwrap().position_ms, 60_000); +} + +#[test] +fn concurrent_offline_sessions_converge_and_keep_both_sessions() { + use ProgressStatus::*; + // Both devices last saw generation 5 and start listening offline. + let generation = ProgressRecord::explicit_generation(Some(5)); + let a_start = progress( + generation, 200, "dev-a", "dev-a:1", 300_000, InProgress, "sa", + ); + let a_cp = progress( + generation, 300, "dev-a", "dev-a:2", 900_000, InProgress, "sa", + ); + let b_start = progress( + generation, 210, "dev-b", "dev-b:1", 300_000, InProgress, "sb", + ); + let b_cp = progress( + generation, 280, "dev-b", "dev-b:2", 1_500_000, InProgress, "sb", + ); + let merged = assert_converges(&[a_start, a_cp.clone(), b_start, b_cp], merge_progress); + // Deterministic: the latest write of the shared generation wins. + assert_eq!(merged, a_cp); + + let session = |id: &str, device: &str, listened: i64, completed: bool| ListenSession { + session_id: id.to_string(), + episode_id: episode_id("e1"), + podcast_id: podcast_id(), + device_id: device.to_string(), + started_at_ms: 200, + ended_at_ms: 300, + start_position_ms: 300_000, + end_position_ms: 900_000, + listened_ms: listened, + completed, + }; + let sessions = [ + session("sa", "dev-a", 600_000, false), + session("sb", "dev-b", 1_200_000, true), + session("sb", "dev-b", 1_200_000, true), + ]; + let mut set: BTreeMap = BTreeMap::new(); + for order in permutations(&sessions) { + set.clear(); + for item in order { + let merged = match set.get(&item.session_id) { + Some(current) => merge_listen_session(current, &item).unwrap(), + None => item.clone(), + }; + set.insert(item.session_id.clone(), merged); + } + assert_eq!(set.len(), 2); + assert_eq!(completed_listen_count(set.values()), 1); + } +} + +#[test] +fn listen_session_versions_only_grow() { + let base = ListenSession { + session_id: "s".to_string(), + episode_id: episode_id("e1"), + podcast_id: podcast_id(), + device_id: "dev-a".to_string(), + started_at_ms: 1_000, + ended_at_ms: 2_000, + start_position_ms: 0, + end_position_ms: 60_000, + listened_ms: 60_000, + completed: false, + }; + let longer = ListenSession { + ended_at_ms: 3_000, + end_position_ms: 120_000, + listened_ms: 120_000, + ..base.clone() + }; + let finished = ListenSession { + ended_at_ms: 3_500, + end_position_ms: 3_600_000, + listened_ms: 125_000, + completed: true, + ..base.clone() + }; + let merged = assert_converges( + &[base.clone(), longer, finished.clone(), base.clone()], + merge_listen_session, + ); + assert_eq!(merged, finished); + assert!(merged.should_record()); + assert_eq!(completed_listen_count([&merged, &merged, &finished]), 1); + + let mut other_episode = base.clone(); + other_episode.episode_id = episode_id("e2"); + assert!(merge_listen_session(&base, &other_episode).is_err()); + let short = ListenSession { + listened_ms: MIN_RECORDED_EPISODE_LISTEN_MS - 1, + ..base.clone() + }; + assert!(!short.should_record()); + assert!( + ListenSession { + listened_ms: MIN_RECORDED_EPISODE_LISTEN_MS, + ..base + } + .should_record() + ); +} + +#[test] +fn completion_criterion() { + // 60 min episode: tail is 30 s. + assert!(!reaches_completion(3_569_999, Some(3_600_000))); + assert!(reaches_completion(3_570_000, Some(3_600_000))); + // 5 min episode: tail is 5 % = 15 s. + assert!(!reaches_completion(284_999, Some(300_000))); + assert!(reaches_completion(285_000, Some(300_000))); + assert!(!reaches_completion(1_000_000, None)); + assert!(!reaches_completion(1_000_000, Some(0))); +} + +fn podcast_meta(title: &str, url: &str) -> PodcastMeta { + PodcastMeta { + feed_url: feed_url(url), + title: title.to_string(), + author: None, + description: None, + link: None, + image_url: None, + } +} + +fn subscription( + subscribed: bool, + hlc_ms: i64, + op: &str, + title: &str, + url: &str, +) -> SubscriptionRecord { + let mut record = SubscriptionRecord { + podcast_id: podcast_id(), + subscribed, + podcast: podcast_meta(title, url), + feed_aliases: Vec::new(), + hlc_ms, + op_id: op.to_string(), + }; + record.normalize(); + record +} + +#[test] +fn subscriptions_converge_for_every_permutation() { + let ops = [ + // Same podcast added on two devices. + subscription(true, 100, "dev-a:1", "Show", "feed"), + subscription(true, 101, "dev-b:1", "Show (B)", "feed"), + // Unsubscribed on A while B was offline. + subscription(false, 200, "dev-a:2", "Show", "feed"), + // B comes back and re-delivers its old state after the feed moved. + subscription(true, 150, "dev-b:2", "Show", "moved"), + subscription(true, 101, "dev-b:1", "Show (B)", "feed"), + ]; + let merged = assert_converges(&ops, merge_subscription); + assert!( + !merged.subscribed, + "unsubscribe survives the offline device" + ); + assert_eq!(merged.op_id, "dev-a:2"); + assert!(merged.feed_aliases.contains(&feed_url("moved"))); + assert!(merged.feed_aliases.contains(&feed_url("feed"))); + merged.validate().unwrap(); +} + +#[test] +fn resubscribing_keeps_progress_and_history() { + use ProgressStatus::*; + let mut progress_register = BTreeMap::new(); + let saved = progress(4, 500, "dev-a", "dev-a:5", 1_234_000, InProgress, "s1"); + progress_register.insert(saved.episode_id.clone(), saved.clone()); + let subscribed = subscription(true, 100, "dev-a:1", "Show", "feed"); + let unsubscribed = subscription(false, 600, "dev-a:6", "Show", "feed"); + let again = subscription(true, 700, "dev-b:1", "Show", "feed"); + let merged = fold(&[subscribed, unsubscribed, again], merge_subscription); + assert!(merged.subscribed); + assert_eq!(progress_register.get(&saved.episode_id), Some(&saved)); +} + +fn share(shared: bool, hlc_ms: i64, op: &str) -> ShareRecord { + ShareRecord { + podcast_id: podcast_id(), + shared, + hlc_ms, + op_id: op.to_string(), + } +} + +#[test] +fn shares_converge_and_false_is_a_tombstone() { + let ops = [ + share(true, 100, "dev-a:1"), + share(false, 200, "dev-a:2"), + share(true, 150, "dev-b:1"), + share(false, 200, "dev-a:2"), + ]; + let merged = assert_converges(&ops, merge_share); + assert!(!merged.shared, "late stale share cannot republish"); +} + +#[test] +fn effective_share_rules() { + let subscribed = subscription(true, 100, "dev-a:1", "Show", "feed"); + let shared = share(true, 150, "dev-a:2"); + assert!(effective_share(Some(&subscribed), Some(&shared))); + assert!(!effective_share(Some(&subscribed), None)); + assert!(!effective_share(None, Some(&shared))); + // New subscriptions are private: a share decision older than the + // latest subscription write does not apply. + let resubscribed = subscription(true, 300, "dev-a:4", "Show", "feed"); + assert!(!effective_share(Some(&resubscribed), Some(&shared))); + // Unsubscribing revokes publication even if a stale share wins. + let unsubscribed = subscription(false, 200, "dev-a:3", "Show", "feed"); + let stale = share(true, 250, "dev-b:1"); + assert!(!effective_share(Some(&unsubscribed), Some(&stale))); +} + +/// Minimal client store used to show that whole operation sets converge and +/// that publisher metadata never reaches personal progress. +#[derive(Debug, Default, Clone, PartialEq)] +struct Store { + subscriptions: BTreeMap, + shares: BTreeMap, + progress: BTreeMap, + sessions: BTreeMap, + catalog: BTreeMap, +} + +#[derive(Debug, Clone)] +enum Op { + Subscription(SubscriptionRecord), + Share(ShareRecord), + Progress(ProgressRecord), + Session(ListenSession), + /// Local RSS refresh: title and audio URL changed at the publisher. + Rss { + title: &'static str, + audio_url: &'static str, + }, +} + +fn upsert( + map: &mut BTreeMap, + key: K, + value: &V, + merge: impl Fn(&V, &V) -> PodcastResult, +) { + let merged = match map.get(&key) { + Some(current) => merge(current, value).unwrap(), + None => value.clone(), + }; + map.insert(key, merged); +} + +impl Store { + fn apply(&mut self, op: &Op) { + match op { + Op::Subscription(record) => upsert( + &mut self.subscriptions, + record.podcast_id.clone(), + record, + merge_subscription, + ), + Op::Share(record) => upsert( + &mut self.shares, + record.podcast_id.clone(), + record, + merge_share, + ), + Op::Progress(record) => upsert( + &mut self.progress, + record.episode_id.clone(), + record, + merge_progress, + ), + Op::Session(session) => upsert( + &mut self.sessions, + session.session_id.clone(), + session, + merge_listen_session, + ), + Op::Rss { title, audio_url } => { + let hints = EpisodeIdentityHints { + guid: Some("e1".to_string()), + enclosure_url: Some(audio_url.to_string()), + link: None, + published_at_ms: Some(1_000), + title: Some(title.to_string()), + }; + let id = resolve_episode_ids(&podcast_id(), None, &[hints], &[])[0] + .clone() + .unwrap(); + // Metadata only: last refresh on this device wins locally. + let meta = EpisodeMeta { + episode_id: id.clone(), + podcast_id: podcast_id(), + guid: Some("e1".to_string()), + title: title.to_string(), + description: None, + season: None, + episode_number: None, + episode_type: EpisodeType::Full, + published_at_ms: Some(1_000), + duration_ms: None, + audio_url: audio_url.to_string(), + mime: None, + byte_len: None, + image_url: None, + link: None, + }; + self.catalog.insert(id, meta); + } + } + } + + fn personal(&self) -> Store { + Store { + catalog: BTreeMap::new(), + ..self.clone() + } + } +} + +#[test] +fn whole_operation_sets_converge_and_rss_never_touches_progress() { + use ProgressStatus::*; + let session = ListenSession { + session_id: "s2".to_string(), + episode_id: episode_id("e1"), + podcast_id: podcast_id(), + device_id: "dev-b".to_string(), + started_at_ms: 10, + ended_at_ms: 20, + start_position_ms: 0, + end_position_ms: 400_000, + listened_ms: 400_000, + completed: false, + }; + let ops = [ + Op::Subscription(subscription(true, 100, "dev-a:1", "Show", "feed")), + Op::Share(share(true, 120, "dev-a:2")), + Op::Progress(progress( + 1, 130, "dev-a", "dev-a:3", 900_000, InProgress, "s1", + )), + Op::Progress(progress( + 2, 125, "dev-b", "dev-b:1", 400_000, InProgress, "s2", + )), + Op::Session(session), + Op::Rss { + title: "Old title", + audio_url: "https://cdn.test/old.mp3", + }, + Op::Rss { + title: "New title", + audio_url: "https://cdn.test/new.mp3", + }, + ]; + let mut reference: Option = None; + for order in permutations(&ops) { + let mut store = Store::default(); + for op in &order { + store.apply(op); + } + // One episode id across both metadata versions. + assert_eq!(store.catalog.len(), 1); + let progress = store.progress.values().next().unwrap(); + assert_eq!(progress.op_id, "dev-b:1"); + assert_eq!(progress.position_ms, 400_000); + let personal = store.personal(); + match &reference { + Some(reference) => assert_eq!(&personal, reference), + None => reference = Some(personal), + } + } +} + +#[test] +fn validation_bounds() { + use ProgressStatus::*; + let ok = progress(1, 1, "dev-a", "dev-a:1", 0, NotStarted, "s"); + ok.validate().unwrap(); + let mut bad = ok.clone(); + bad.position_ms = -1; + assert!(bad.validate().is_err()); + let mut bad = ok.clone(); + bad.session_id = String::new(); + assert!(bad.validate().is_err()); + let mut bad = ok; + bad.device_id = "d".repeat(crate::podcast::MAX_TOKEN_BYTES + 1); + assert!(bad.validate().is_err()); + + let mut record = subscription(true, 1, "dev-a:1", "Show", "feed"); + record.feed_aliases = (0..=crate::podcast::MAX_FEED_ALIASES + 1) + .map(|i| feed_url(&format!("alias-{i}"))) + .collect(); + assert!(record.validate().is_err()); + record.normalize(); + record.validate().unwrap(); +} + +#[test] +fn progress_json_shape() { + let record = progress( + 3, + 42, + "dev-a", + "dev-a:7", + 1_000, + ProgressStatus::InProgress, + "s", + ); + let json = serde_json::to_value(&record).unwrap(); + assert_eq!(json["status"], "in_progress"); + assert_eq!(json["generation"], 3); + assert_eq!( + serde_json::from_value::(json).unwrap(), + record + ); +}