Add shared podcast contract to music-dht

Introduce music_dht::podcast, a pure module (no SQLite, HTTP or clock)
that every Furumi client uses for podcast identity and personal state:

- FeedUrl canonicalization that keeps the path and every query
  parameter byte-for-byte, PodcastId/EpisodeId derivation with
  domain-separated BLAKE3, feed aliases and the documented no-GUID
  episode identity rule;
- bounded PodcastMeta, EpisodeMeta and the self-contained
  PodcastEpisodeRef queue item;
- convergent merge rules for subscriptions (LWW, unsubscribe is state),
  share decisions (false is a tombstone), progress registers ordered by
  a Lamport generation, and listening sessions (G-set, one completion
  per session).

Tests cover every delivery permutation of small operation sets, late
checkpoints of old sessions, concurrent offline sessions and RSS
metadata updates that must not touch progress.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-19 15:39:50 +02:00
1 parent b191c10ba4
commit 38e49c4926
8 files changed
+3154

No files matched your search

+1
View File
@@ -92,6 +92,7 @@ pub mod jam;
mod message;
mod node;
mod normalization;
pub mod podcast;
mod record;
mod request;
mod routing;
+507
View File
@@ -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<Self> {
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<Self> {
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<String> for FeedUrl {
type Error = PodcastError;
fn try_from(value: String) -> PodcastResult<Self> {
if canonicalize(&value)? == value {
Ok(Self(value))
} else {
Err(invalid("feed URL is not in canonical form"))
}
}
}
impl From<FeedUrl> for String {
fn from(value: FeedUrl) -> String {
value.0
}
}
impl AsRef<str> 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<String> {
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::<u32>() {
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<String> {
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<Item = (&'a PodcastId, &'a FeedUrl)>,
) -> 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<FeedUrl> {
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<FeedUrl> = 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::<FeedUrl>(&json).unwrap(), url);
assert!(serde_json::from_str::<FeedUrl>("\"HTTPS://example.com/rss\"").is_err());
assert!(serde_json::from_str::<FeedUrl>("\"https://example.com/rss#x\"").is_err());
assert!(serde_json::from_str::<FeedUrl>("\"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<FeedUrl> = (0..(MAX_FEED_ALIASES + 4))
.map(|i| FeedUrl::parse(&format!("https://a.test/{i:02}")).unwrap())
.collect();
let a: Vec<FeedUrl> = urls[..5].to_vec();
let b: Vec<FeedUrl> = urls[3..].iter().cloned().chain([origin.clone()]).collect();
let c: Vec<FeedUrl> = 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]));
}
}
+343
View File
@@ -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<Self> {
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> {
Self::parse(value)
}
}
impl TryFrom<String> for $name {
type Error = PodcastError;
fn try_from(value: String) -> PodcastResult<Self> {
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<str> 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 `<id>`).
///
/// Returns `None` when the GUID is blank or longer than [`MAX_GUID_BYTES`].
pub fn from_guid(podcast: &PodcastId, guid: &str) -> Option<Self> {
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:` + `<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 `<guid>` or Atom `<id>`.
Guid(String),
/// Item `<link>`.
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<Self> {
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<Self> {
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<Self> {
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<Self> {
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::<PodcastId>(&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::<PodcastId>("\"pod1:xyz\"").is_err());
// Non-canonical trailing bits: last char encodes 1 data bit + 4 zero bits.
let mut chars: Vec<char> = 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());
}
}
+512
View File
@@ -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 `<guid>` / Atom `<id>`, when present.
#[serde(default)]
pub guid: Option<String>,
/// Enclosure (audio) URL.
#[serde(default)]
pub enclosure_url: Option<String>,
/// Item `<link>`.
#[serde(default)]
pub link: Option<String>,
/// Publication time in unix milliseconds.
#[serde(default)]
pub published_at_ms: Option<i64>,
/// Item title.
#[serde(default)]
pub title: Option<String>,
}
impl EpisodeIdentityHints {
fn guid_key(&self) -> Option<EpisodeKey> {
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 `<link>` 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<EpisodeId> {
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 `<link>`, 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: `<link>`,
/// then `(date, title)`, then enclosure URL.
///
/// A `<link>` 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<Option<EpisodeId>> {
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<Usable<'_>> = 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<EpisodeId> = BTreeSet::new();
let mut out: Vec<Option<EpisodeId>> = 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<i64>,
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<EpisodeId> {
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<EpisodeIdentityHints> = (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<KnownEpisode> = 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));
}
}
+480
View File
@@ -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<String> 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<String>,
/// Plain-text description, at most [`MAX_DESCRIPTION_CHARS`].
#[serde(default)]
pub description: Option<String>,
/// Publisher web page.
#[serde(default)]
pub link: Option<String>,
/// Artwork URL.
#[serde(default)]
pub image_url: Option<String>,
}
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<String>,
/// Episode title.
pub title: String,
/// Plain-text description, at most [`MAX_DESCRIPTION_CHARS`].
#[serde(default)]
pub description: Option<String>,
/// `itunes:season`. Episodes without a season form their own group.
#[serde(default)]
pub season: Option<u32>,
/// `itunes:episode`.
#[serde(default)]
pub episode_number: Option<u32>,
/// `itunes:episodeType`.
#[serde(default)]
pub episode_type: EpisodeType,
/// Publication time in unix milliseconds.
#[serde(default)]
pub published_at_ms: Option<i64>,
/// Duration announced by the publisher, in milliseconds.
#[serde(default)]
pub duration_ms: Option<i64>,
/// Absolute http(s) audio URL at the publisher.
pub audio_url: String,
/// Enclosure MIME type.
#[serde(default)]
pub mime: Option<String>,
/// Enclosure length in bytes.
#[serde(default)]
pub byte_len: Option<u64>,
/// Episode artwork URL.
#[serde(default)]
pub image_url: Option<String>,
/// Episode web page.
#[serde(default)]
pub link: Option<String>,
}
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<String>,
/// Announced duration in milliseconds.
#[serde(default)]
pub duration_ms: Option<i64>,
/// Publication time in unix milliseconds.
#[serde(default)]
pub published_at_ms: Option<i64>,
/// `itunes:season`.
#[serde(default)]
pub season: Option<u32>,
/// `itunes:episode`.
#[serde(default)]
pub episode_number: Option<u32>,
/// Episode or podcast artwork URL.
#[serde(default)]
pub image_url: Option<String>,
}
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<i64>) -> 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<String> {
value
.map(str::trim)
.filter(|value| !value.is_empty())
.map(|value| bounded_text(value, max_chars))
}
fn valid_url(value: Option<&str>) -> Option<String> {
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::<EpisodeType>("\"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::<EpisodeMeta>(&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::<PodcastEpisodeRef>(&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::<PodcastEpisodeRef>(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);
}
}
+298
View File
@@ -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, `<link>`
//! or (date, normalized title) and only then derives a new id from the
//! first available fallback key.
//!
//! # Personal state
//!
//! * [`SubscriptionRecord`]: last-writer-wins by `(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<T> = std::result::Result<T, PodcastError>;
/// Truncates `text` to at most `max_chars` characters, ending with `…` when cut.
///
/// Clients use it to fit publisher metadata into the contract bounds.
pub fn bounded_text(text: &str, max_chars: usize) -> String {
if text.chars().count() <= max_chars {
return text.to_string();
}
if max_chars == 0 {
return String::new();
}
let mut out: String = text.chars().take(max_chars - 1).collect();
out.push('…');
out
}
pub(crate) fn check_text(
field: &'static str,
value: &str,
max_chars: usize,
required: bool,
) -> PodcastResult<()> {
if required && value.trim().is_empty() {
return Err(PodcastError::InvalidField {
field,
reason: "must not be empty",
});
}
if value.len() > max_chars * 4 || value.chars().count() > max_chars {
return Err(PodcastError::InvalidField {
field,
reason: "is too long",
});
}
Ok(())
}
pub(crate) fn check_opt_text(
field: &'static str,
value: Option<&str>,
max_chars: usize,
) -> PodcastResult<()> {
value.map_or(Ok(()), |value| check_text(field, value, max_chars, false))
}
pub(crate) fn check_token(field: &'static str, value: &str) -> PodcastResult<()> {
if value.is_empty() {
return Err(PodcastError::InvalidField {
field,
reason: "must not be empty",
});
}
if value.len() > MAX_TOKEN_BYTES {
return Err(PodcastError::InvalidField {
field,
reason: "is too long",
});
}
if value.chars().any(|c| c.is_control()) {
return Err(PodcastError::InvalidField {
field,
reason: "contains control characters",
});
}
Ok(())
}
/// Returns whether `value` is an absolute `http`/`https` URL with a host,
/// without whitespace or control characters and within [`MAX_URL_BYTES`].
///
/// Media URLs keep the publisher's spelling; only feed URLs are canonicalized.
pub fn is_http_url(value: &str) -> bool {
if value.is_empty()
|| value.len() > MAX_URL_BYTES
|| value.chars().any(|c| c.is_whitespace() || c.is_control())
{
return false;
}
let lower_prefix = |prefix: &str| {
value.len() >= prefix.len() && value[..prefix.len()].eq_ignore_ascii_case(prefix)
};
let rest = if lower_prefix("http://") {
&value[7..]
} else if lower_prefix("https://") {
&value[8..]
} else {
return false;
};
let authority = rest.split(['/', '?', '#']).next().unwrap_or_default();
let host = authority.rsplit('@').next().unwrap_or_default();
!host.is_empty() && !host.starts_with(':')
}
pub(crate) fn check_url(field: &'static str, value: &str) -> PodcastResult<()> {
if is_http_url(value) {
Ok(())
} else {
Err(PodcastError::InvalidField {
field,
reason: "must be an absolute http(s) URL",
})
}
}
pub(crate) fn check_opt_url(field: &'static str, value: Option<&str>) -> PodcastResult<()> {
value.map_or(Ok(()), |value| check_url(field, value))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn bounded_text_cuts_on_char_boundaries() {
assert_eq!(bounded_text("hello", 5), "hello");
assert_eq!(bounded_text("hello!", 5), "hell…");
assert_eq!(bounded_text("привет", 3), "пр…");
assert_eq!(bounded_text("x", 0), "");
}
#[test]
fn text_limits_accept_the_limit_and_reject_one_more() {
let at = "я".repeat(MAX_TITLE_CHARS);
let over = "я".repeat(MAX_TITLE_CHARS + 1);
assert!(check_text("title", &at, MAX_TITLE_CHARS, true).is_ok());
assert!(check_text("title", &over, MAX_TITLE_CHARS, true).is_err());
assert!(check_text("title", " ", MAX_TITLE_CHARS, true).is_err());
assert!(check_text("title", "", MAX_TITLE_CHARS, false).is_ok());
}
#[test]
fn token_limits() {
assert!(check_token("op_id", &"a".repeat(MAX_TOKEN_BYTES)).is_ok());
assert!(check_token("op_id", &"a".repeat(MAX_TOKEN_BYTES + 1)).is_err());
assert!(check_token("op_id", "").is_err());
assert!(check_token("op_id", "a\nb").is_err());
}
#[test]
fn http_urls() {
assert!(is_http_url("https://cdn.example.test/a.mp3?x=1"));
assert!(is_http_url("HTTP://cdn.example.test"));
assert!(!is_http_url("ftp://cdn.example.test/a.mp3"));
assert!(!is_http_url("file:///etc/passwd"));
assert!(!is_http_url("https://"));
assert!(!is_http_url("https:///path"));
assert!(!is_http_url("https://a.test/my file.mp3"));
assert!(!is_http_url(""));
let long = format!("https://a.test/{}", "x".repeat(MAX_URL_BYTES));
assert!(!is_http_url(&long));
let at = format!("https://a.test/{}", "x".repeat(MAX_URL_BYTES - 15));
assert_eq!(at.len(), MAX_URL_BYTES);
assert!(is_http_url(&at));
}
}
+445
View File
@@ -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<i64>) -> 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>) -> 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<ProgressRecord> {
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<FeedUrl>,
/// 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<SubscriptionRecord> {
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<ShareRecord> {
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<ListenSession> {
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<Item = &'a ListenSession>) -> usize {
sessions
.into_iter()
.filter(|session| session.completed)
.map(|session| session.session_id.as_str())
.collect::<BTreeSet<_>>()
.len()
}
#[cfg(test)]
#[path = "state_tests.rs"]
mod tests;
+568
View File
@@ -0,0 +1,568 @@
use std::collections::BTreeMap;
use super::*;
use crate::podcast::{EpisodeIdentityHints, EpisodeMeta, EpisodeType, resolve_episode_ids};
fn permutations<T: Clone>(items: &[T]) -> Vec<Vec<T>> {
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<T: Clone>(items: &[T], merge: impl Fn(&T, &T) -> PodcastResult<T>) -> 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<T: Clone + PartialEq + std::fmt::Debug>(
items: &[T],
merge: impl Fn(&T, &T) -> PodcastResult<T> + 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<String, ListenSession> = 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<PodcastId, SubscriptionRecord>,
shares: BTreeMap<PodcastId, ShareRecord>,
progress: BTreeMap<EpisodeId, ProgressRecord>,
sessions: BTreeMap<String, ListenSession>,
catalog: BTreeMap<EpisodeId, EpisodeMeta>,
}
#[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<K: Ord + Clone, V: Clone>(
map: &mut BTreeMap<K, V>,
key: K,
value: &V,
merge: impl Fn(&V, &V) -> PodcastResult<V>,
) {
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<Store> = 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::<ProgressRecord>(json).unwrap(),
record
);
}