Merge remote-tracking branch 'origin/main' into issue/18-transmission

Cargo.lock

@@ -87,10 +87,23 @@ version = "0.1.0"
 [[package]]
 name = "arr-meta"
 version = "0.1.0"
+dependencies = [
+ "chrono",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "thiserror",
+ "tokio",
+ "tracing",
+ "wiremock",
+]
 
 [[package]]
 name = "arr-parse"
 version = "0.1.0"
+dependencies = [
+ "serde",
+]
 
 [[package]]
 name = "arr-probe"
@@ -216,6 +229,7 @@ checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
 dependencies = [
  "iana-time-zone",
  "num-traits",
+ "serde",
  "windows-link",
 ]
 

crates/arr-meta/Cargo.toml

@@ -7,6 +7,16 @@ repository.workspace = true
 publish = false
 
 [dependencies]
+chrono.workspace = true
+reqwest.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+tracing.workspace = true
+
+[dev-dependencies]
+tokio.workspace = true
+wiremock.workspace = true
 
 [lints]
 workspace = true

crates/arr-meta/src/cache.rs

@@ -0,0 +1,69 @@
+//! A small time-to-live cache over raw response bodies.
+//!
+//! Keyed on a logical request key rather than the URL, so the API key never
+//! becomes part of a cache key. Bodies are stored unparsed: parsing again on a
+//! hit costs microseconds and keeps one cache serving every endpoint.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::sync::{Mutex, PoisonError};
+use std::time::{Duration, Instant};
+
+#[derive(Debug)]
+struct Entry {
+    stored_at: Instant,
+    body: Arc<str>,
+}
+
+#[derive(Debug)]
+pub(crate) struct Cache {
+    ttl: Duration,
+    entries: Mutex<HashMap<String, Entry>>,
+}
+
+impl Cache {
+    pub(crate) fn new(ttl: Duration) -> Self {
+        Self {
+            ttl,
+            entries: Mutex::new(HashMap::new()),
+        }
+    }
+
+    /// The cached body for `key`, if one is present and still fresh.
+    pub(crate) fn get(&self, key: &str) -> Option<Arc<str>> {
+        let mut entries = self.entries.lock().unwrap_or_else(PoisonError::into_inner);
+        let entry = entries.get(key)?;
+        if entry.stored_at.elapsed() < self.ttl {
+            return Some(Arc::clone(&entry.body));
+        }
+        entries.remove(key);
+        None
+    }
+
+    pub(crate) fn insert(&self, key: String, body: Arc<str>) {
+        let mut entries = self.entries.lock().unwrap_or_else(PoisonError::into_inner);
+        entries.insert(
+            key,
+            Entry {
+                stored_at: Instant::now(),
+                body,
+            },
+        );
+    }
+
+    pub(crate) fn remove(&self, key: &str) {
+        self.entries
+            .lock()
+            .unwrap_or_else(PoisonError::into_inner)
+            .remove(key);
+    }
+
+    /// Drop everything. The daily metadata refresh does not need this — entries
+    /// expire on their own — but a forced refresh from the UI does.
+    pub(crate) fn clear(&self) {
+        self.entries
+            .lock()
+            .unwrap_or_else(PoisonError::into_inner)
+            .clear();
+    }
+}

crates/arr-meta/src/client.rs

@@ -0,0 +1,275 @@
+//! The TMDB HTTP client.
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use reqwest::{StatusCode, Url};
+use serde::de::DeserializeOwned;
+
+use crate::cache::Cache;
+use crate::error::{Error, Result};
+use crate::model::{Movie, MovieSearchResult, RawMovie, RawSearchPage};
+
+/// TMDB's v3 API root.
+pub const DEFAULT_BASE_URL: &str = "https://api.themoviedb.org/3/";
+
+/// One day. Metadata refresh is a daily tick (§8), not a per-request cost.
+pub const DEFAULT_CACHE_TTL: Duration = Duration::from_hours(24);
+
+const DEFAULT_TIMEOUT: Duration = Duration::from_secs(10);
+
+/// How much of an unexpected response body is worth keeping in an error.
+const MAX_ERROR_BODY: usize = 512;
+
+/// A TMDB client with an in-process response cache.
+///
+/// Deliberately not `Clone`: the cache lives inside it, so build one and share
+/// it behind an `Arc` rather than handing out copies that each miss.
+pub struct TmdbClient {
+    http: reqwest::Client,
+    base_url: Url,
+    api_key: String,
+    cache: Cache,
+}
+
+/// Deliberately hand-written: a derived `Debug` would print the API key.
+impl std::fmt::Debug for TmdbClient {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("TmdbClient")
+            .field("http", &self.http)
+            .field("base_url", &self.base_url.as_str())
+            .field("api_key", &"<redacted>")
+            .field("cache", &self.cache)
+            .finish()
+    }
+}
+
+impl TmdbClient {
+    /// A client against the real TMDB with default timeouts and cache lifetime.
+    ///
+    /// # Errors
+    ///
+    /// Fails if the HTTP client cannot be constructed.
+    pub fn new(api_key: impl Into<String>) -> Result<Self> {
+        Self::builder(api_key).build()
+    }
+
+    /// Start configuring a client.
+    #[must_use]
+    pub fn builder(api_key: impl Into<String>) -> TmdbClientBuilder {
+        TmdbClientBuilder {
+            api_key: api_key.into(),
+            base_url: DEFAULT_BASE_URL.to_owned(),
+            cache_ttl: DEFAULT_CACHE_TTL,
+            timeout: DEFAULT_TIMEOUT,
+        }
+    }
+
+    /// Search TMDB for movies by title, optionally narrowed to a year.
+    ///
+    /// Returns the first page of results, which is what a search box shows.
+    ///
+    /// # Errors
+    ///
+    /// Any of [`Error`]; see its variants for what callers should distinguish.
+    pub async fn search_movies(
+        &self,
+        query: &str,
+        year: Option<i32>,
+    ) -> Result<Vec<MovieSearchResult>> {
+        let mut params = vec![
+            ("query", query.trim().to_owned()),
+            ("include_adult", "false".to_owned()),
+        ];
+        if let Some(year) = year {
+            params.push(("year", year.to_string()));
+        }
+
+        let page: RawSearchPage = self.get_json("search/movie", &params).await?;
+        Ok(page.results.into_iter().map(Into::into).collect())
+    }
+
+    /// Full detail for one movie, including the digital release date.
+    ///
+    /// One HTTP call: release dates come back appended to the same response
+    /// rather than costing a second round trip.
+    ///
+    /// # Errors
+    ///
+    /// [`Error::NotFound`] when TMDB has no such id, otherwise any of [`Error`].
+    pub async fn movie(&self, tmdb_id: u32) -> Result<Movie> {
+        let path = format!("movie/{tmdb_id}");
+        let params = [("append_to_response", "release_dates".to_owned())];
+        let raw: RawMovie = self.get_json(&path, &params).await?;
+        Ok(raw.into())
+    }
+
+    /// Drop every cached response. For a user-initiated "refresh metadata".
+    pub fn clear_cache(&self) {
+        self.cache.clear();
+    }
+
+    /// Fetch and decode, caching only what decoded.
+    ///
+    /// Decoding before the insert matters: a malformed response that got into
+    /// the cache would keep returning [`Error::Decode`] for the whole
+    /// time-to-live, turning one bad response into a day-long outage for that
+    /// title.
+    async fn get_json<T: DeserializeOwned>(
+        &self,
+        path: &str,
+        params: &[(&str, String)],
+    ) -> Result<T> {
+        let (url, cache_key) = self.request_url(path, params)?;
+
+        if let Some(hit) = self.cache.get(&cache_key) {
+            tracing::trace!(cache_key, "TMDB cache hit");
+            return serde_json::from_str(&hit).map_err(|err| {
+                // Unreachable in practice — nothing enters the cache until it
+                // has decoded once — but evicting beats serving a stuck error.
+                self.cache.remove(&cache_key);
+                Error::from(err)
+            });
+        }
+
+        let body = self.fetch(url, path).await?;
+        let value = serde_json::from_str(&body)?;
+        self.cache.insert(cache_key, Arc::from(body));
+        Ok(value)
+    }
+
+    /// The request URL, and the cache key derived from it.
+    ///
+    /// Both come from the same `Url`, so the key is percent-encoded exactly as
+    /// the request is. Building the key separately by string concatenation is
+    /// how `query = "dune&year=2024"` collides with `query = "dune", year =
+    /// 2024` — two different requests, one cache entry.
+    ///
+    /// The API key is deliberately not in the URL yet: it is appended at send
+    /// time so it can never reach a cache key or a log line.
+    fn request_url(&self, path: &str, params: &[(&str, String)]) -> Result<(Url, String)> {
+        let mut url = self
+            .base_url
+            .join(path)
+            .map_err(|err| Error::BaseUrl(err.to_string()))?;
+        {
+            let mut pairs = url.query_pairs_mut();
+            for (name, value) in params {
+                pairs.append_pair(name, value);
+            }
+        }
+
+        let cache_key = match url.query() {
+            Some(query) => format!("{}?{}", url.path(), query),
+            None => url.path().to_owned(),
+        };
+
+        Ok((url, cache_key))
+    }
+
+    /// `resource` names the thing being fetched for [`Error::NotFound`], in the
+    /// caller's terms rather than as a URL.
+    async fn fetch(&self, mut url: Url, resource: &str) -> Result<String> {
+        url.query_pairs_mut().append_pair("api_key", &self.api_key);
+
+        tracing::debug!(resource, "TMDB request");
+        let response = self.http.get(url).send().await?;
+        let status = response.status();
+
+        if status.is_success() {
+            return Ok(response.text().await?);
+        }
+
+        // Failures are never cached: a rate limit or an outage must not pin a
+        // title into a bad state for a day.
+        Err(match status {
+            StatusCode::UNAUTHORIZED | StatusCode::FORBIDDEN => Error::Unauthorized,
+            StatusCode::NOT_FOUND => Error::NotFound {
+                resource: resource.to_owned(),
+            },
+            StatusCode::TOO_MANY_REQUESTS => Error::RateLimited {
+                retry_after: retry_after(&response),
+            },
+            other => {
+                let body = response.text().await.unwrap_or_default();
+                Error::Unexpected {
+                    status: other.as_u16(),
+                    body: body.chars().take(MAX_ERROR_BODY).collect(),
+                }
+            }
+        })
+    }
+}
+
+fn retry_after(response: &reqwest::Response) -> Option<Duration> {
+    response
+        .headers()
+        .get(reqwest::header::RETRY_AFTER)?
+        .to_str()
+        .ok()?
+        .trim()
+        .parse::<u64>()
+        .ok()
+        .map(Duration::from_secs)
+}
+
+/// Configuration for a [`TmdbClient`].
+#[derive(Debug, Clone)]
+pub struct TmdbClientBuilder {
+    api_key: String,
+    base_url: String,
+    cache_ttl: Duration,
+    timeout: Duration,
+}
+
+impl TmdbClientBuilder {
+    /// Point the client somewhere other than TMDB. Tests use this; nothing else
+    /// should.
+    #[must_use]
+    pub fn base_url(mut self, base_url: impl Into<String>) -> Self {
+        self.base_url = base_url.into();
+        self
+    }
+
+    /// How long a cached response stays fresh.
+    #[must_use]
+    pub fn cache_ttl(mut self, cache_ttl: Duration) -> Self {
+        self.cache_ttl = cache_ttl;
+        self
+    }
+
+    /// Per-request timeout.
+    #[must_use]
+    pub fn timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = timeout;
+        self
+    }
+
+    /// Build the client.
+    ///
+    /// # Errors
+    ///
+    /// [`Error::BaseUrl`] if the base URL will not parse, [`Error::Transport`]
+    /// if the HTTP client cannot be built.
+    pub fn build(self) -> Result<TmdbClient> {
+        // Without a trailing slash `Url::join` replaces the last path segment
+        // instead of appending, which silently drops the `/3`.
+        let mut base_url = self.base_url;
+        if !base_url.ends_with('/') {
+            base_url.push('/');
+        }
+        let base_url = Url::parse(&base_url).map_err(|err| Error::BaseUrl(err.to_string()))?;
+
+        let http = reqwest::Client::builder()
+            .timeout(self.timeout)
+            .user_agent(concat!("arr/", env!("CARGO_PKG_VERSION")))
+            .build()?;
+
+        Ok(TmdbClient {
+            http,
+            base_url,
+            api_key: self.api_key,
+            cache: Cache::new(self.cache_ttl),
+        })
+    }
+}

crates/arr-meta/src/error.rs

@@ -0,0 +1,56 @@
+//! Errors the TMDB client can produce.
+
+use std::time::Duration;
+
+/// Result alias for every fallible operation in this crate.
+pub type Result<T> = std::result::Result<T, Error>;
+
+/// Everything that can go wrong talking to TMDB.
+///
+/// The distinction that matters to callers is between "this title does not
+/// exist" ([`Error::NotFound`]), "back off" ([`Error::RateLimited`]) and
+/// "TMDB is unreachable" ([`Error::Transport`]) — the last is a §9.5 *broken*
+/// notification, the first two are not.
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum Error {
+    /// The request never completed: DNS, TLS, connection or timeout.
+    #[error("TMDB request failed")]
+    Transport(#[from] reqwest::Error),
+
+    /// TMDB rejected the API key.
+    #[error("TMDB rejected the API key")]
+    Unauthorized,
+
+    /// TMDB has no record of the thing that was asked for.
+    #[error("TMDB has no record of {resource}")]
+    NotFound {
+        /// The logical resource that was requested, e.g. `movie/693134`.
+        resource: String,
+    },
+
+    /// TMDB is rate limiting. `retry_after` is the `Retry-After` header when
+    /// TMDB sent one.
+    #[error("TMDB rate limit reached")]
+    RateLimited {
+        /// How long TMDB asked us to wait, when it said.
+        retry_after: Option<Duration>,
+    },
+
+    /// Any other non-success status.
+    #[error("TMDB returned HTTP {status}")]
+    Unexpected {
+        /// The HTTP status code.
+        status: u16,
+        /// The response body, truncated to something loggable.
+        body: String,
+    },
+
+    /// The response parsed as JSON but not into the shape expected.
+    #[error("TMDB response did not match the expected shape")]
+    Decode(#[from] serde_json::Error),
+
+    /// The configured base URL is not a URL.
+    #[error("invalid TMDB base URL: {0}")]
+    BaseUrl(String),
+}

crates/arr-meta/src/lib.rs

@@ -1 +1,26 @@
-//! arr-meta — see DESIGN.md.
+//! arr-meta — TMDB client. See `DESIGN.md` §5.2, §6.2 and §12.
+//!
+//! Two fields carry the weight here and neither is decoration:
+//!
+//! - `original_language` (plus the origin country that disambiguates `pt`) is
+//!   what the whole dub rule in §5.2 is expressed against.
+//! - The digital release date gates targeted search (§6.2). A movie with no
+//!   digital release date must get zero searches.
+//!
+//! Responses are cached in process with a time-to-live, defaulting to a day,
+//! because metadata refresh is a daily tick (§8) and not a per-request cost.
+
+// `unused_crate_dependencies` is a per-target lint and the library's own test
+// target links the dev-dependencies without using them. The real uses are in
+// `tests/`.
+#[cfg(test)]
+use {tokio as _, wiremock as _};
+
+mod cache;
+mod client;
+mod error;
+mod model;
+
+pub use client::{TmdbClient, TmdbClientBuilder, DEFAULT_BASE_URL, DEFAULT_CACHE_TTL};
+pub use error::{Error, Result};
+pub use model::{Movie, MovieSearchResult};

crates/arr-meta/src/model.rs

@@ -0,0 +1,257 @@
+//! The slice of TMDB's schema this project actually reads.
+//!
+//! TMDB returns a great deal more than this. Everything kept here is either
+//! shown to a person or fed to the policy engine; the rest is dropped at the
+//! edge so nothing downstream has to know TMDB's field names.
+
+use chrono::{Datelike, NaiveDate};
+use serde::{Deserialize, Serialize};
+
+/// TMDB's release-date type for a digital release. See §6.2 — this is the one
+/// that gates targeted search.
+const RELEASE_TYPE_DIGITAL: u8 = 4;
+
+/// One row of a TMDB search.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct MovieSearchResult {
+    /// TMDB's own id, the key everything else hangs off.
+    pub tmdb_id: u32,
+    /// Title in the requested language.
+    pub title: String,
+    /// Title in the original language.
+    pub original_title: String,
+    /// ISO 639-1, e.g. `en` or `pt`. See [`Movie::original_language`] for why
+    /// this alone is not enough for Portuguese.
+    pub original_language: String,
+    /// Primary (theatrical) release date. Absent for announced-but-undated
+    /// titles, where TMDB sends an empty string.
+    pub release_date: Option<NaiveDate>,
+    /// TMDB's synopsis, empty string normalised away.
+    pub overview: Option<String>,
+    /// Path fragment, not a URL. TMDB's image base is a separate concern.
+    pub poster_path: Option<String>,
+}
+
+impl MovieSearchResult {
+    /// Release year, when TMDB has a release date at all.
+    #[must_use]
+    pub fn year(&self) -> Option<i32> {
+        self.release_date.map(|date| date.year())
+    }
+}
+
+/// A movie as TMDB describes it, reduced to what this project uses.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Movie {
+    /// TMDB's own id.
+    pub tmdb_id: u32,
+    /// `IMDb` id, when TMDB knows one. Torznab `t=movie` searches take it.
+    pub imdb_id: Option<String>,
+    /// Title in the requested language.
+    pub title: String,
+    /// Title in the original language.
+    pub original_title: String,
+    /// ISO 639-1, e.g. `en` or `pt`.
+    ///
+    /// The dub rule in §5.2 compares a track's language against this. ISO
+    /// 639-1 has one code for both Portuguese variants, so `pt` on its own
+    /// cannot tell a Brazilian film from a Portuguese one — pair it with
+    /// [`Movie::origin_countries`] to resolve that.
+    pub original_language: String,
+    /// ISO 3166-1 alpha-2 country codes the title originates from. Needed to
+    /// read `pt` as pt-BR or pt-PT.
+    pub origin_countries: Vec<String>,
+    /// Primary (theatrical) release date.
+    pub release_date: Option<NaiveDate>,
+    /// Earliest digital release date TMDB records, across every country.
+    ///
+    /// §6.2: a movie with no digital release date gets zero targeted searches.
+    /// Earliest-anywhere is the right reading of that — a release existing in
+    /// one region is a release that exists on the indexers.
+    pub digital_release: Option<NaiveDate>,
+    /// Runtime in minutes, when known.
+    pub runtime: Option<u32>,
+    /// TMDB's own status string: `Released`, `Post Production`, and so on.
+    pub status: String,
+    /// TMDB's synopsis, empty string normalised away.
+    pub overview: Option<String>,
+    /// Path fragment, not a URL.
+    pub poster_path: Option<String>,
+}
+
+impl Movie {
+    /// Release year, when TMDB has a release date at all.
+    #[must_use]
+    pub fn year(&self) -> Option<i32> {
+        self.release_date.map(|date| date.year())
+    }
+
+    /// Whether a digital release exists as of `on`.
+    ///
+    /// This is the §6.2 gate in one place: no digital date at all, or a date
+    /// still in the future, means the release does not exist yet and searching
+    /// for it is a wasted query.
+    #[must_use]
+    pub fn is_digitally_released(&self, on: NaiveDate) -> bool {
+        self.digital_release.is_some_and(|date| date <= on)
+    }
+}
+
+// --- TMDB wire types -------------------------------------------------------
+//
+// Private on purpose. TMDB's field names stop here.
+
+#[derive(Debug, Deserialize)]
+pub(crate) struct RawSearchPage {
+    #[serde(default)]
+    pub(crate) results: Vec<RawSearchResult>,
+}
+
+#[derive(Debug, Deserialize)]
+pub(crate) struct RawSearchResult {
+    id: u32,
+    #[serde(default)]
+    title: String,
+    #[serde(default)]
+    original_title: String,
+    #[serde(default)]
+    original_language: String,
+    #[serde(default)]
+    release_date: Option<String>,
+    #[serde(default)]
+    overview: Option<String>,
+    #[serde(default)]
+    poster_path: Option<String>,
+}
+
+impl From<RawSearchResult> for MovieSearchResult {
+    fn from(raw: RawSearchResult) -> Self {
+        Self {
+            tmdb_id: raw.id,
+            title: raw.title,
+            original_title: raw.original_title,
+            original_language: raw.original_language,
+            release_date: raw.release_date.as_deref().and_then(parse_date),
+            overview: non_empty(raw.overview),
+            poster_path: non_empty(raw.poster_path),
+        }
+    }
+}
+
+#[derive(Debug, Deserialize)]
+pub(crate) struct RawMovie {
+    id: u32,
+    #[serde(default)]
+    imdb_id: Option<String>,
+    #[serde(default)]
+    title: String,
+    #[serde(default)]
+    original_title: String,
+    #[serde(default)]
+    original_language: String,
+    #[serde(default)]
+    origin_country: Vec<String>,
+    #[serde(default)]
+    production_countries: Vec<RawProductionCountry>,
+    #[serde(default)]
+    release_date: Option<String>,
+    #[serde(default)]
+    runtime: Option<u32>,
+    #[serde(default)]
+    status: String,
+    #[serde(default)]
+    overview: Option<String>,
+    #[serde(default)]
+    poster_path: Option<String>,
+    #[serde(default)]
+    release_dates: Option<RawReleaseDates>,
+}
+
+#[derive(Debug, Deserialize)]
+struct RawProductionCountry {
+    iso_3166_1: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct RawReleaseDates {
+    #[serde(default)]
+    results: Vec<RawCountryReleaseDates>,
+}
+
+#[derive(Debug, Deserialize)]
+struct RawCountryReleaseDates {
+    #[serde(default)]
+    release_dates: Vec<RawReleaseDate>,
+}
+
+#[derive(Debug, Deserialize)]
+struct RawReleaseDate {
+    #[serde(rename = "type")]
+    kind: u8,
+    #[serde(default)]
+    release_date: Option<String>,
+}
+
+impl From<RawMovie> for Movie {
+    fn from(raw: RawMovie) -> Self {
+        let digital_release = raw
+            .release_dates
+            .as_ref()
+            .and_then(|dates| earliest_digital(&dates.results));
+
+        // `origin_country` is the newer field and the more precise one;
+        // `production_countries` is the fallback for records that predate it.
+        let origin_countries = if raw.origin_country.is_empty() {
+            raw.production_countries
+                .into_iter()
+                .map(|country| country.iso_3166_1)
+                .collect()
+        } else {
+            raw.origin_country
+        };
+
+        Self {
+            tmdb_id: raw.id,
+            imdb_id: non_empty(raw.imdb_id),
+            title: raw.title,
+            original_title: raw.original_title,
+            original_language: raw.original_language,
+            origin_countries,
+            release_date: raw.release_date.as_deref().and_then(parse_date),
+            digital_release,
+            runtime: raw.runtime,
+            status: raw.status,
+            overview: non_empty(raw.overview),
+            poster_path: non_empty(raw.poster_path),
+        }
+    }
+}
+
+fn earliest_digital(countries: &[RawCountryReleaseDates]) -> Option<NaiveDate> {
+    countries
+        .iter()
+        .flat_map(|country| country.release_dates.iter())
+        .filter(|entry| entry.kind == RELEASE_TYPE_DIGITAL)
+        .filter_map(|entry| entry.release_date.as_deref().and_then(parse_datetime))
+        .min()
+}
+
+/// TMDB sends `""` rather than `null` for a date it does not have.
+fn parse_date(raw: &str) -> Option<NaiveDate> {
+    NaiveDate::parse_from_str(raw, "%Y-%m-%d").ok()
+}
+
+/// Release-date entries are timestamps: `2024-04-16T00:00:00.000Z`. The clock
+/// part is meaningless — TMDB stamps a local date as UTC midnight — so only
+/// the date survives.
+fn parse_datetime(raw: &str) -> Option<NaiveDate> {
+    chrono::DateTime::parse_from_rfc3339(raw)
+        .ok()
+        .map(|stamp| stamp.date_naive())
+        .or_else(|| parse_date(raw))
+}
+
+/// TMDB uses `""` where `null` is meant, in most string fields.
+fn non_empty(value: Option<String>) -> Option<String> {
+    value.filter(|text| !text.is_empty())
+}

crates/arr-meta/tests/fixtures/movie_cidade_de_deus.json

@@ -0,0 +1,51 @@
+{
+  "adult": false,
+  "backdrop_path": "/pdtzEreKvKAlqa2YEBaGwiA45V8.jpg",
+  "budget": 3300000,
+  "genres": [{ "id": 18, "name": "Drama" }, { "id": 80, "name": "Crime" }],
+  "homepage": "",
+  "id": 598,
+  "imdb_id": "tt0317248",
+  "origin_country": ["BR"],
+  "original_language": "pt",
+  "original_title": "Cidade de Deus",
+  "overview": "In the slums of Rio, two kids' paths diverge as one struggles to become a photographer and the other a kingpin.",
+  "popularity": 38.9,
+  "poster_path": "/k7eYdWvhYQyRQoU2TB2A2Xu2TfD.jpg",
+  "production_countries": [{ "iso_3166_1": "BR", "name": "Brazil" }],
+  "release_date": "2002-02-05",
+  "revenue": 30641770,
+  "runtime": 130,
+  "spoken_languages": [{ "english_name": "Portuguese", "iso_639_1": "pt", "name": "Português" }],
+  "status": "Released",
+  "tagline": "If you run you're dead. If you stay, you're dead again. Period.",
+  "title": "City of God",
+  "video": false,
+  "vote_average": 8.4,
+  "vote_count": 8123,
+  "release_dates": {
+    "results": [
+      {
+        "iso_3166_1": "BR",
+        "release_dates": [
+          {
+            "certification": "18",
+            "descriptors": [],
+            "iso_639_1": "",
+            "note": "",
+            "release_date": "2002-08-30T00:00:00.000Z",
+            "type": 3
+          },
+          {
+            "certification": "",
+            "descriptors": [],
+            "iso_639_1": "",
+            "note": "",
+            "release_date": "2016-05-10T00:00:00.000Z",
+            "type": 4
+          }
+        ]
+      }
+    ]
+  }
+}

crates/arr-meta/tests/fixtures/movie_dune.json

@@ -0,0 +1,83 @@
+{
+  "adult": false,
+  "backdrop_path": "/xOMo8BRK7PfcJv9JCnx7s5hj0PX.jpg",
+  "budget": 190000000,
+  "genres": [{ "id": 878, "name": "Science Fiction" }, { "id": 12, "name": "Adventure" }],
+  "homepage": "https://www.dunemovie.com",
+  "id": 693134,
+  "imdb_id": "tt15239678",
+  "origin_country": ["US"],
+  "original_language": "en",
+  "original_title": "Dune: Part Two",
+  "overview": "Follow the mythic journey of Paul Atreides as he unites with Chani and the Fremen while on a path of revenge against the conspirators who destroyed his family.",
+  "popularity": 234.53,
+  "poster_path": "/1pdfLvkbY9ohJlCjQH2CZjjYVvJ.jpg",
+  "production_countries": [
+    { "iso_3166_1": "US", "name": "United States of America" },
+    { "iso_3166_1": "CA", "name": "Canada" }
+  ],
+  "release_date": "2024-02-27",
+  "revenue": 711844358,
+  "runtime": 167,
+  "spoken_languages": [{ "english_name": "English", "iso_639_1": "en", "name": "English" }],
+  "status": "Released",
+  "tagline": "Long live the fighters.",
+  "title": "Dune: Part Two",
+  "video": false,
+  "vote_average": 8.157,
+  "vote_count": 6104,
+  "release_dates": {
+    "results": [
+      {
+        "iso_3166_1": "US",
+        "release_dates": [
+          {
+            "certification": "PG-13",
+            "descriptors": [],
+            "iso_639_1": "",
+            "note": "",
+            "release_date": "2024-03-01T00:00:00.000Z",
+            "type": 3
+          },
+          {
+            "certification": "",
+            "descriptors": [],
+            "iso_639_1": "",
+            "note": "",
+            "release_date": "2024-04-16T00:00:00.000Z",
+            "type": 4
+          },
+          {
+            "certification": "PG-13",
+            "descriptors": [],
+            "iso_639_1": "",
+            "note": "",
+            "release_date": "2024-05-14T00:00:00.000Z",
+            "type": 5
+          }
+        ]
+      },
+      {
+        "iso_3166_1": "PT",
+        "release_dates": [
+          {
+            "certification": "M/12",
+            "descriptors": [],
+            "iso_639_1": "",
+            "note": "",
+            "release_date": "2024-02-28T00:00:00.000Z",
+            "type": 3
+          },
+          {
+            "certification": "",
+            "descriptors": [],
+            "iso_639_1": "",
+            "note": "",
+            "release_date": "2024-04-10T00:00:00.000Z",
+            "type": 4
+          }
+        ]
+      }
+    ]
+  }
+}

crates/arr-meta/tests/fixtures/movie_future_digital.json

@@ -0,0 +1,51 @@
+{
+  "adult": false,
+  "backdrop_path": null,
+  "budget": 0,
+  "genres": [{ "id": 28, "name": "Action" }],
+  "homepage": "",
+  "id": 1211073,
+  "imdb_id": "tt31852248",
+  "origin_country": ["GB"],
+  "original_language": "en",
+  "original_title": "Dated For Later",
+  "overview": "A film with an announced but not yet reached digital release date.",
+  "popularity": 88.0,
+  "poster_path": "/placeholder.jpg",
+  "production_countries": [{ "iso_3166_1": "GB", "name": "United Kingdom" }],
+  "release_date": "2026-07-10",
+  "revenue": 0,
+  "runtime": 110,
+  "spoken_languages": [{ "english_name": "English", "iso_639_1": "en", "name": "English" }],
+  "status": "Released",
+  "tagline": "",
+  "title": "Dated For Later",
+  "video": false,
+  "vote_average": 6.4,
+  "vote_count": 40,
+  "release_dates": {
+    "results": [
+      {
+        "iso_3166_1": "GB",
+        "release_dates": [
+          {
+            "certification": "15",
+            "descriptors": [],
+            "iso_639_1": "",
+            "note": "",
+            "release_date": "2026-07-10T00:00:00.000Z",
+            "type": 3
+          },
+          {
+            "certification": "",
+            "descriptors": [],
+            "iso_639_1": "",
+            "note": "",
+            "release_date": "2026-11-20T00:00:00.000Z",
+            "type": 4
+          }
+        ]
+      }
+    ]
+  }
+}

crates/arr-meta/tests/fixtures/movie_theatrical_only.json

@@ -0,0 +1,43 @@
+{
+  "adult": false,
+  "backdrop_path": null,
+  "budget": 0,
+  "genres": [{ "id": 18, "name": "Drama" }],
+  "homepage": "",
+  "id": 1022789,
+  "imdb_id": "tt27675327",
+  "origin_country": ["US"],
+  "original_language": "en",
+  "original_title": "Still In Cinemas",
+  "overview": "A film that has opened theatrically and has no digital release yet.",
+  "popularity": 120.4,
+  "poster_path": "/placeholder.jpg",
+  "production_countries": [{ "iso_3166_1": "US", "name": "United States of America" }],
+  "release_date": "2026-08-01",
+  "revenue": 0,
+  "runtime": 96,
+  "spoken_languages": [{ "english_name": "English", "iso_639_1": "en", "name": "English" }],
+  "status": "Released",
+  "tagline": "",
+  "title": "Still In Cinemas",
+  "video": false,
+  "vote_average": 7.1,
+  "vote_count": 210,
+  "release_dates": {
+    "results": [
+      {
+        "iso_3166_1": "US",
+        "release_dates": [
+          {
+            "certification": "PG",
+            "descriptors": [],
+            "iso_639_1": "",
+            "note": "",
+            "release_date": "2026-08-01T00:00:00.000Z",
+            "type": 3
+          }
+        ]
+      }
+    ]
+  }
+}

crates/arr-meta/tests/fixtures/movie_unreleased.json

@@ -0,0 +1,27 @@
+{
+  "adult": false,
+  "backdrop_path": null,
+  "budget": 0,
+  "genres": [{ "id": 878, "name": "Science Fiction" }],
+  "homepage": "",
+  "id": 1156593,
+  "imdb_id": "",
+  "origin_country": [],
+  "original_language": "en",
+  "original_title": "Dune: Part Three",
+  "overview": "",
+  "popularity": 41.2,
+  "poster_path": null,
+  "production_countries": [],
+  "release_date": "",
+  "revenue": 0,
+  "runtime": null,
+  "spoken_languages": [],
+  "status": "Post Production",
+  "tagline": "",
+  "title": "Dune: Part Three",
+  "video": false,
+  "vote_average": 0.0,
+  "vote_count": 0,
+  "release_dates": { "results": [] }
+}

crates/arr-meta/tests/fixtures/search_dune.json

@@ -0,0 +1,39 @@
+{
+  "page": 1,
+  "results": [
+    {
+      "adult": false,
+      "backdrop_path": "/xOMo8BRK7PfcJv9JCnx7s5hj0PX.jpg",
+      "genre_ids": [878, 12],
+      "id": 693134,
+      "original_language": "en",
+      "original_title": "Dune: Part Two",
+      "overview": "Follow the mythic journey of Paul Atreides as he unites with Chani and the Fremen while on a path of revenge against the conspirators who destroyed his family.",
+      "popularity": 234.53,
+      "poster_path": "/1pdfLvkbY9ohJlCjQH2CZjjYVvJ.jpg",
+      "release_date": "2024-02-27",
+      "title": "Dune: Part Two",
+      "video": false,
+      "vote_average": 8.157,
+      "vote_count": 6104
+    },
+    {
+      "adult": false,
+      "backdrop_path": null,
+      "genre_ids": [878],
+      "id": 1156593,
+      "original_language": "en",
+      "original_title": "Dune: Part Three",
+      "overview": "",
+      "popularity": 41.2,
+      "poster_path": null,
+      "release_date": "",
+      "title": "Dune: Part Three",
+      "video": false,
+      "vote_average": 0.0,
+      "vote_count": 0
+    }
+  ],
+  "total_pages": 1,
+  "total_results": 2
+}

crates/arr-meta/tests/tmdb.rs

@@ -0,0 +1,463 @@
+//! TMDB client tests. Everything runs against `wiremock` — DESIGN.md §12 rules
+//! out live calls, which would rate-limit and leak a key into CI.
+
+// Same per-target quirk as in `lib.rs`: an integration test links the library's
+// dependencies without using them directly.
+use {reqwest as _, serde as _, serde_json as _, thiserror as _, tracing as _};
+
+use std::time::Duration;
+
+use arr_meta::{Error, TmdbClient};
+use chrono::NaiveDate;
+use wiremock::matchers::{header_exists, method, path, query_param};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+const SEARCH_DUNE: &str = include_str!("fixtures/search_dune.json");
+const MOVIE_DUNE: &str = include_str!("fixtures/movie_dune.json");
+const MOVIE_CIDADE_DE_DEUS: &str = include_str!("fixtures/movie_cidade_de_deus.json");
+const MOVIE_UNRELEASED: &str = include_str!("fixtures/movie_unreleased.json");
+const MOVIE_THEATRICAL_ONLY: &str = include_str!("fixtures/movie_theatrical_only.json");
+const MOVIE_FUTURE_DIGITAL: &str = include_str!("fixtures/movie_future_digital.json");
+
+fn client(server: &MockServer) -> TmdbClient {
+    TmdbClient::builder("test-key")
+        .base_url(format!("{}/3", server.uri()))
+        .build()
+        .expect("client builds")
+}
+
+fn date(year: i32, month: u32, day: u32) -> NaiveDate {
+    NaiveDate::from_ymd_opt(year, month, day).expect("valid date")
+}
+
+async fn mount_movie(server: &MockServer, tmdb_id: u32, body: &str) {
+    Mock::given(method("GET"))
+        .and(path(format!("/3/movie/{tmdb_id}")))
+        .respond_with(ResponseTemplate::new(200).set_body_string(body))
+        .mount(server)
+        .await;
+}
+
+#[tokio::test]
+async fn search_parses_results_and_normalises_empty_strings() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/3/search/movie"))
+        .respond_with(ResponseTemplate::new(200).set_body_string(SEARCH_DUNE))
+        .mount(&server)
+        .await;
+
+    let results = client(&server)
+        .search_movies("dune", None)
+        .await
+        .expect("search succeeds");
+
+    assert_eq!(results.len(), 2);
+
+    let released = &results[0];
+    assert_eq!(released.tmdb_id, 693_134);
+    assert_eq!(released.title, "Dune: Part Two");
+    assert_eq!(released.original_language, "en");
+    assert_eq!(released.release_date, Some(date(2024, 2, 27)));
+    assert_eq!(released.year(), Some(2024));
+    assert!(released.poster_path.is_some());
+
+    // TMDB sends "" rather than null for a date it does not have, and for an
+    // overview it does not have either.
+    let announced = &results[1];
+    assert_eq!(announced.release_date, None);
+    assert_eq!(announced.year(), None);
+    assert_eq!(announced.overview, None);
+    assert_eq!(announced.poster_path, None);
+}
+
+#[tokio::test]
+async fn search_sends_the_query_year_and_api_key() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/3/search/movie"))
+        .and(query_param("query", "dune"))
+        .and(query_param("year", "2024"))
+        .and(query_param("api_key", "test-key"))
+        .and(query_param("include_adult", "false"))
+        .respond_with(ResponseTemplate::new(200).set_body_string(SEARCH_DUNE))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    client(&server)
+        .search_movies("  dune  ", Some(2024))
+        .await
+        .expect("search succeeds");
+}
+
+#[tokio::test]
+async fn movie_detail_asks_for_release_dates_in_one_call() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/3/movie/693134"))
+        .and(query_param("append_to_response", "release_dates"))
+        .and(header_exists("user-agent"))
+        .respond_with(ResponseTemplate::new(200).set_body_string(MOVIE_DUNE))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    client(&server)
+        .movie(693_134)
+        .await
+        .expect("lookup succeeds");
+}
+
+#[tokio::test]
+async fn movie_detail_carries_the_policy_relevant_fields() {
+    let server = MockServer::start().await;
+    mount_movie(&server, 693_134, MOVIE_DUNE).await;
+
+    let movie = client(&server)
+        .movie(693_134)
+        .await
+        .expect("lookup succeeds");
+
+    assert_eq!(movie.tmdb_id, 693_134);
+    assert_eq!(movie.imdb_id.as_deref(), Some("tt15239678"));
+    assert_eq!(movie.title, "Dune: Part Two");
+    assert_eq!(movie.original_title, "Dune: Part Two");
+    assert_eq!(movie.original_language, "en");
+    assert_eq!(movie.origin_countries, vec!["US".to_owned()]);
+    assert_eq!(movie.release_date, Some(date(2024, 2, 27)));
+    assert_eq!(movie.runtime, Some(167));
+    assert_eq!(movie.status, "Released");
+    assert_eq!(movie.year(), Some(2024));
+}
+
+/// §5.2: a Brazilian film's own soundtrack must pass the pt-BR dub rule, which
+/// only works if the origin country survives alongside the bare `pt` code.
+#[tokio::test]
+async fn brazilian_film_keeps_its_language_and_origin_country() {
+    let server = MockServer::start().await;
+    mount_movie(&server, 598, MOVIE_CIDADE_DE_DEUS).await;
+
+    let movie = client(&server).movie(598).await.expect("lookup succeeds");
+
+    assert_eq!(movie.original_language, "pt");
+    assert_eq!(movie.origin_countries, vec!["BR".to_owned()]);
+}
+
+/// §6.2. Earliest digital date anywhere: the release existing in one region is
+/// a release that exists on the indexers.
+#[tokio::test]
+async fn digital_release_is_the_earliest_across_every_country() {
+    let server = MockServer::start().await;
+    mount_movie(&server, 693_134, MOVIE_DUNE).await;
+
+    let movie = client(&server)
+        .movie(693_134)
+        .await
+        .expect("lookup succeeds");
+
+    // US digital is 2024-04-16, PT digital is 2024-04-10. Theatrical (type 3)
+    // and physical (type 5) entries must not be mistaken for it.
+    assert_eq!(movie.digital_release, Some(date(2024, 4, 10)));
+    assert!(movie.is_digitally_released(date(2024, 4, 10)));
+    assert!(movie.is_digitally_released(date(2026, 1, 1)));
+    assert!(!movie.is_digitally_released(date(2024, 4, 9)));
+}
+
+/// §6.2, the case that costs Radarr the most queries: no digital date means no
+/// targeted search at all.
+#[tokio::test]
+async fn theatrical_only_movie_has_no_digital_release() {
+    let server = MockServer::start().await;
+    mount_movie(&server, 1_022_789, MOVIE_THEATRICAL_ONLY).await;
+
+    let movie = client(&server)
+        .movie(1_022_789)
+        .await
+        .expect("lookup succeeds");
+
+    assert_eq!(movie.release_date, Some(date(2026, 8, 1)));
+    assert_eq!(movie.digital_release, None);
+    assert!(!movie.is_digitally_released(date(2026, 8, 22)));
+}
+
+#[tokio::test]
+async fn announced_digital_date_does_not_count_until_it_arrives() {
+    let server = MockServer::start().await;
+    mount_movie(&server, 1_211_073, MOVIE_FUTURE_DIGITAL).await;
+
+    let movie = client(&server)
+        .movie(1_211_073)
+        .await
+        .expect("lookup succeeds");
+
+    assert_eq!(movie.digital_release, Some(date(2026, 11, 20)));
+    assert!(!movie.is_digitally_released(date(2026, 8, 22)));
+    assert!(movie.is_digitally_released(date(2026, 11, 20)));
+}
+
+#[tokio::test]
+async fn unreleased_movie_has_no_dates_and_no_imdb_id() {
+    let server = MockServer::start().await;
+    mount_movie(&server, 1_156_593, MOVIE_UNRELEASED).await;
+
+    let movie = client(&server)
+        .movie(1_156_593)
+        .await
+        .expect("lookup succeeds");
+
+    assert_eq!(movie.release_date, None);
+    assert_eq!(movie.digital_release, None);
+    assert_eq!(movie.imdb_id, None);
+    assert_eq!(movie.runtime, None);
+    assert!(movie.origin_countries.is_empty());
+    assert!(!movie.is_digitally_released(date(2026, 8, 22)));
+}
+
+/// §8: metadata refresh is a daily tick, so repeated lookups within a day must
+/// not become repeated requests.
+#[tokio::test]
+async fn responses_are_served_from_the_cache() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/3/movie/693134"))
+        .respond_with(ResponseTemplate::new(200).set_body_string(MOVIE_DUNE))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = client(&server);
+    let first = client.movie(693_134).await.expect("lookup succeeds");
+    let second = client.movie(693_134).await.expect("cached lookup succeeds");
+
+    assert_eq!(first, second);
+}
+
+#[tokio::test]
+async fn cache_entries_expire_and_can_be_cleared() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/3/movie/693134"))
+        .respond_with(ResponseTemplate::new(200).set_body_string(MOVIE_DUNE))
+        .expect(3)
+        .mount(&server)
+        .await;
+
+    let client = TmdbClient::builder("test-key")
+        .base_url(format!("{}/3", server.uri()))
+        .cache_ttl(Duration::from_millis(50))
+        .build()
+        .expect("client builds");
+
+    client.movie(693_134).await.expect("lookup succeeds");
+    tokio::time::sleep(Duration::from_millis(120)).await;
+    client.movie(693_134).await.expect("lookup succeeds");
+
+    client.clear_cache();
+    client.movie(693_134).await.expect("lookup succeeds");
+}
+
+#[tokio::test]
+async fn different_searches_do_not_share_a_cache_entry() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/3/search/movie"))
+        .respond_with(ResponseTemplate::new(200).set_body_string(SEARCH_DUNE))
+        .expect(3)
+        .mount(&server)
+        .await;
+
+    let client = client(&server);
+    client.search_movies("dune", None).await.expect("succeeds");
+    client
+        .search_movies("dune", Some(2024))
+        .await
+        .expect("succeeds");
+    client.search_movies("bluey", None).await.expect("succeeds");
+    // A repeat of the first is the cached one.
+    client.search_movies("dune", None).await.expect("succeeds");
+}
+
+#[tokio::test]
+async fn unknown_id_is_not_found() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/3/movie/1"))
+        .respond_with(ResponseTemplate::new(404).set_body_string(
+            r#"{"success":false,"status_code":34,"status_message":"The resource you requested could not be found."}"#,
+        ))
+        .mount(&server)
+        .await;
+
+    let error = client(&server).movie(1).await.expect_err("404 is an error");
+
+    match error {
+        Error::NotFound { resource } => assert_eq!(resource, "movie/1"),
+        other => panic!("expected NotFound, got {other:?}"),
+    }
+}
+
+#[tokio::test]
+async fn rejected_key_is_unauthorized() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/3/movie/693134"))
+        .respond_with(ResponseTemplate::new(401).set_body_string(
+            r#"{"success":false,"status_code":7,"status_message":"Invalid API key: You must be granted a valid key."}"#,
+        ))
+        .mount(&server)
+        .await;
+
+    let error = client(&server)
+        .movie(693_134)
+        .await
+        .expect_err("401 is an error");
+
+    assert!(matches!(error, Error::Unauthorized), "got {error:?}");
+}
+
+#[tokio::test]
+async fn rate_limit_surfaces_retry_after() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/3/movie/693134"))
+        .respond_with(
+            ResponseTemplate::new(429)
+                .insert_header("retry-after", "13")
+                .set_body_string(r#"{"status_code":25,"status_message":"Your request count is over the allowed limit."}"#),
+        )
+        .mount(&server)
+        .await;
+
+    let error = client(&server)
+        .movie(693_134)
+        .await
+        .expect_err("429 is an error");
+
+    match error {
+        Error::RateLimited { retry_after } => {
+            assert_eq!(retry_after, Some(Duration::from_secs(13)));
+        }
+        other => panic!("expected RateLimited, got {other:?}"),
+    }
+}
+
+/// A TMDB outage must not pin a title into a bad state for a whole day.
+#[tokio::test]
+async fn failures_are_not_cached() {
+    let server = MockServer::start().await;
+    let client = client(&server);
+
+    {
+        let _failing = Mock::given(method("GET"))
+            .and(path("/3/movie/693134"))
+            .respond_with(ResponseTemplate::new(500).set_body_string("upstream is down"))
+            .expect(1)
+            .mount_as_scoped(&server)
+            .await;
+
+        let error = client.movie(693_134).await.expect_err("500 is an error");
+        match error {
+            Error::Unexpected { status, body } => {
+                assert_eq!(status, 500);
+                assert_eq!(body, "upstream is down");
+            }
+            other => panic!("expected Unexpected, got {other:?}"),
+        }
+    }
+
+    Mock::given(method("GET"))
+        .and(path("/3/movie/693134"))
+        .respond_with(ResponseTemplate::new(200).set_body_string(MOVIE_DUNE))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let movie = client.movie(693_134).await.expect("retry succeeds");
+    assert_eq!(movie.tmdb_id, 693_134);
+}
+
+/// A body that does not decode must not enter the cache, or one bad response
+/// becomes a day-long outage for that title.
+#[tokio::test]
+async fn malformed_json_is_a_decode_error_and_is_not_cached() {
+    let server = MockServer::start().await;
+    let client = client(&server);
+
+    {
+        let _garbage = Mock::given(method("GET"))
+            .and(path("/3/movie/693134"))
+            .respond_with(ResponseTemplate::new(200).set_body_string("{ not json"))
+            .expect(1)
+            .mount_as_scoped(&server)
+            .await;
+
+        let error = client
+            .movie(693_134)
+            .await
+            .expect_err("garbage is an error");
+        assert!(matches!(error, Error::Decode(_)), "got {error:?}");
+    }
+
+    Mock::given(method("GET"))
+        .and(path("/3/movie/693134"))
+        .respond_with(ResponseTemplate::new(200).set_body_string(MOVIE_DUNE))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let movie = client.movie(693_134).await.expect("retry succeeds");
+    assert_eq!(movie.tmdb_id, 693_134);
+}
+
+/// The cache key is derived from the encoded URL, so a query that happens to
+/// contain `&year=` cannot collide with the same query plus a real year.
+#[tokio::test]
+async fn a_query_containing_separators_does_not_collide_with_a_year() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/3/search/movie"))
+        .respond_with(ResponseTemplate::new(200).set_body_string(SEARCH_DUNE))
+        .expect(2)
+        .mount(&server)
+        .await;
+
+    let client = client(&server);
+    client
+        .search_movies("dune&year=2024", None)
+        .await
+        .expect("succeeds");
+    client
+        .search_movies("dune", Some(2024))
+        .await
+        .expect("succeeds");
+}
+
+/// The API key is appended at send time, so it can never become part of a
+/// cache key.
+#[tokio::test]
+async fn a_query_that_spells_out_the_api_key_is_still_just_a_query() {
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/3/search/movie"))
+        .and(query_param("query", "dune&api_key=stolen"))
+        .and(query_param("api_key", "test-key"))
+        .respond_with(ResponseTemplate::new(200).set_body_string(SEARCH_DUNE))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    client(&server)
+        .search_movies("dune&api_key=stolen", None)
+        .await
+        .expect("succeeds");
+}
+
+#[tokio::test]
+async fn debug_output_does_not_leak_the_api_key() {
+    let server = MockServer::start().await;
+    let rendered = format!("{:?}", client(&server));
+
+    assert!(!rendered.contains("test-key"), "{rendered}");
+    assert!(rendered.contains("redacted"), "{rendered}");
+}

crates/arr-parse/Cargo.toml

@@ -7,6 +7,7 @@ repository.workspace = true
 publish = false
 
 [dependencies]
+serde = { workspace = true }
 
 [lints]
 workspace = true

crates/arr-parse/src/lib.rs

@@ -1 +1,481 @@
-//! arr-parse — see DESIGN.md.
+//! Release name parsing.
+//!
+//! Everything extracted here is a *claim*, not a fact (`DESIGN.md` §5.6):
+//! release names lie or omit. Claims drive pre-grab filtering and scoring
+//! only. Post-download truth comes from `ffprobe` and lives in different
+//! types downstream — never mix the two in one struct.
+//!
+//! Parsing never fails: a malformed name yields a partial [`NameClaims`],
+//! worst case an empty one.
+
+mod markers;
+
+use serde::{Deserialize, Serialize};
+
+use crate::markers::{Marker, Strength};
+
+/// Claimed video resolution. Ordered worst to best.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+pub enum Resolution {
+    /// 480p or 480i.
+    #[serde(rename = "480p")]
+    P480,
+    /// 576p or 576i.
+    #[serde(rename = "576p")]
+    P576,
+    /// 720p.
+    #[serde(rename = "720p")]
+    P720,
+    /// 1080p or 1080i.
+    #[serde(rename = "1080p")]
+    P1080,
+    /// 2160p, also claimed by `4K` and `UHD` markers.
+    #[serde(rename = "2160p")]
+    P2160,
+}
+
+/// Claimed source tier. Ordered worst to best per `DESIGN.md` §5.5; the
+/// bottom four are hard filters there, not low scores.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+pub enum Source {
+    /// Camcorder in a cinema.
+    Cam,
+    /// Telesync.
+    Telesync,
+    /// Telecine.
+    Telecine,
+    /// Screener copy.
+    Screener,
+    /// DVD or a DVD rip.
+    Dvd,
+    /// Over-the-air capture.
+    Hdtv,
+    /// Re-encoded streaming capture.
+    WebRip,
+    /// Untouched streaming download.
+    WebDl,
+    /// `BluRay` encode.
+    BluRay,
+    /// Untouched `BluRay` streams.
+    Remux,
+}
+
+/// Claimed video codec.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum Codec {
+    /// H.264 / AVC.
+    X264,
+    /// H.265 / HEVC.
+    X265,
+    /// AV1.
+    Av1,
+    /// `XviD` / `DivX`.
+    Xvid,
+}
+
+/// Claimed HDR format markers. A name may carry several (`DV HDR10`), and a
+/// `DV` claim says nothing about the profile — that is `ffprobe`'s job
+/// (`DESIGN.md` §5.3).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum HdrMarker {
+    /// `DV`, `DoVi`, `Dolby Vision`.
+    DolbyVision,
+    /// HDR10+.
+    Hdr10Plus,
+    /// HDR10.
+    Hdr10,
+    /// Generic `HDR` with no format named.
+    Hdr,
+    /// Hybrid log-gamma.
+    Hlg,
+    /// Explicitly SDR.
+    Sdr,
+}
+
+/// Claimed language markers. `PtBr` and `Dual` are the first of the three
+/// pt-BR detection signals in `DESIGN.md` §5.2; interpretation belongs to
+/// the policy engine, this crate only reports what the name says.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum LanguageMarker {
+    /// `PT-BR`, `Dublado`, `Nacional`.
+    PtBr,
+    /// `PT-PT`.
+    PtPt,
+    /// `Portuguese`/`POR`/`PT` — flavour unknown.
+    Portuguese,
+    /// English.
+    English,
+    /// French.
+    French,
+    /// German.
+    German,
+    /// Spanish, including `Latino` and `Castellano`.
+    Spanish,
+    /// Italian.
+    Italian,
+    /// `MULTi` — several audio languages advertised.
+    Multi,
+    /// `DUAL` / `Dual Áudio` — two audio tracks, a common pt-BR signal.
+    Dual,
+}
+
+/// Claimed edition markers.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum Edition {
+    /// Extended cut or edition.
+    Extended,
+    /// Director's cut.
+    DirectorsCut,
+    /// Theatrical cut.
+    Theatrical,
+    /// Unrated.
+    Unrated,
+    /// Uncut.
+    Uncut,
+    /// IMAX.
+    Imax,
+    /// Remastered.
+    Remastered,
+    /// Criterion release.
+    Criterion,
+    /// Special edition.
+    SpecialEdition,
+    /// `LIMITED` theatrical run.
+    Limited,
+}
+
+/// What a release name claims about itself. Every field is unverified
+/// (`DESIGN.md` §5.6); absence of a marker means nothing.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(default)]
+pub struct NameClaims {
+    /// Title words before the year / first quality marker, if any survived.
+    pub title: Option<String>,
+    /// Claimed release year.
+    pub year: Option<u16>,
+    /// Claimed resolution.
+    pub resolution: Option<Resolution>,
+    /// Claimed source tier. `Remux` wins when both it and `BluRay` appear.
+    pub source: Option<Source>,
+    /// Claimed video codec.
+    pub codec: Option<Codec>,
+    /// Claimed HDR markers, in order of appearance, deduplicated.
+    pub hdr: Vec<HdrMarker>,
+    /// Claimed language markers, in order of appearance, deduplicated.
+    pub languages: Vec<LanguageMarker>,
+    /// Claimed editions, in order of appearance, deduplicated.
+    pub editions: Vec<Edition>,
+    /// Claimed release group.
+    pub group: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+struct Token {
+    orig: String,
+    low: String,
+}
+
+/// Parse a release name into [`NameClaims`]. Never panics; unrecognised
+/// input degrades to partial or empty claims.
+#[must_use]
+pub fn parse(name: &str) -> NameClaims {
+    let trimmed = name.trim();
+    let stripped = strip_extension(trimmed);
+    let (cleaned, bracket_group) = take_trailing_bracket_group(stripped);
+    let mut toks = tokenize(&cleaned);
+    strip_site_prefix(&mut toks);
+
+    let has_strong = first_strong_index(&toks).is_some();
+    let dash_group = take_dash_group(&mut toks, has_strong);
+    let first_strong = first_strong_index(&toks);
+
+    let limit = first_strong.unwrap_or(toks.len());
+    let year_positions: Vec<usize> = toks
+        .iter()
+        .enumerate()
+        .skip(1)
+        .filter(|(_, t)| markers::year_of(&t.low).is_some())
+        .map(|(i, _)| i)
+        .collect();
+    let year_idx = year_positions
+        .iter()
+        .rev()
+        .find(|&&i| i < limit)
+        .or_else(|| year_positions.first())
+        .copied();
+    let boundary = year_idx.map_or(limit, |y| y.min(limit));
+
+    let mut claims = NameClaims {
+        year: year_idx
+            .and_then(|i| toks.get(i))
+            .and_then(|t| markers::year_of(&t.low)),
+        group: dash_group.or(bracket_group),
+        ..NameClaims::default()
+    };
+
+    let mut title_toks: Vec<Token> = toks.get(..boundary).unwrap_or_default().to_vec();
+    strip_title_editions(&mut title_toks, &mut claims.editions);
+    if !title_toks.is_empty() {
+        let words: Vec<&str> = title_toks.iter().map(|t| t.orig.as_str()).collect();
+        claims.title = Some(words.join(" "));
+    }
+
+    let mut sources: Vec<Source> = Vec::new();
+    let mut i = boundary;
+    while i < toks.len() {
+        if Some(i) == year_idx || markers::is_season_episode(&toks[i].low) {
+            i += 1;
+            continue;
+        }
+        if let Some(next) = toks.get(i + 1) {
+            if Some(i + 1) != year_idx {
+                if let Some((m, _)) = markers::classify_pair(&toks[i].low, &next.low) {
+                    apply_marker(&mut claims, &mut sources, m);
+                    i += 2;
+                    continue;
+                }
+            }
+        }
+        if let Some((m, _)) = markers::classify(&toks[i].low) {
+            apply_marker(&mut claims, &mut sources, m);
+        }
+        i += 1;
+    }
+
+    claims.source = if sources.contains(&Source::Remux) {
+        Some(Source::Remux)
+    } else {
+        sources.first().copied()
+    };
+    claims
+}
+
+fn apply_marker(claims: &mut NameClaims, sources: &mut Vec<Source>, m: Marker) {
+    match m {
+        Marker::Resolution(r) => {
+            if claims.resolution.is_none() {
+                claims.resolution = Some(r);
+            }
+        }
+        Marker::Source(s) => {
+            if !sources.contains(&s) {
+                sources.push(s);
+            }
+        }
+        Marker::Codec(c) => {
+            if claims.codec.is_none() {
+                claims.codec = Some(c);
+            }
+        }
+        Marker::Hdr(h) => {
+            if !claims.hdr.contains(&h) {
+                claims.hdr.push(h);
+            }
+        }
+        Marker::Language(l) => {
+            if !claims.languages.contains(&l) {
+                claims.languages.push(l);
+            }
+        }
+        Marker::Edition(e) => {
+            if !claims.editions.contains(&e) {
+                claims.editions.push(e);
+            }
+        }
+        Marker::Audio | Marker::Junk => {}
+    }
+}
+
+/// Pop edition markers off the tail of the title region ("Movie Extended
+/// 2024" carries an edition, not a longer title). Always leaves at least
+/// one title token.
+fn strip_title_editions(title_toks: &mut Vec<Token>, editions: &mut Vec<Edition>) {
+    loop {
+        let n = title_toks.len();
+        if n >= 3 {
+            if let (Some(a), Some(b)) = (title_toks.get(n - 2), title_toks.get(n - 1)) {
+                if let Some((Marker::Edition(e), _)) = markers::classify_pair(&a.low, &b.low) {
+                    if !editions.contains(&e) {
+                        editions.insert(0, e);
+                    }
+                    title_toks.truncate(n - 2);
+                    continue;
+                }
+            }
+        }
+        if n >= 2 {
+            if let Some(last) = title_toks.get(n - 1) {
+                if let Some((Marker::Edition(e), _)) = markers::classify(&last.low) {
+                    if !editions.contains(&e) {
+                        editions.insert(0, e);
+                    }
+                    title_toks.truncate(n - 1);
+                    continue;
+                }
+            }
+        }
+        break;
+    }
+}
+
+/// Index of the first token that unambiguously marks the end of the title:
+/// a strong marker, a strong pair, or a season/episode tag.
+fn first_strong_index(toks: &[Token]) -> Option<usize> {
+    for (i, tok) in toks.iter().enumerate() {
+        if markers::is_season_episode(&tok.low) {
+            return Some(i);
+        }
+        if let Some(next) = toks.get(i + 1) {
+            if let Some((_, Strength::Strong)) = markers::classify_pair(&tok.low, &next.low) {
+                return Some(i);
+            }
+        }
+        if let Some((_, Strength::Strong)) = markers::classify(&tok.low) {
+            return Some(i);
+        }
+    }
+    None
+}
+
+fn tokenize(s: &str) -> Vec<Token> {
+    s.split(|c: char| {
+        matches!(
+            c,
+            '.' | '_' | '[' | ']' | '(' | ')' | '{' | '}' | ',' | ';' | '!' | '?'
+        ) || c.is_whitespace()
+    })
+    .filter(|t| !t.is_empty())
+    .map(|t| Token {
+        orig: t.to_string(),
+        low: t.to_lowercase(),
+    })
+    .collect()
+}
+
+/// Drop a leading `www.<site>.<tld>` tag.
+fn strip_site_prefix(toks: &mut Vec<Token>) {
+    if toks.first().is_some_and(|t| t.low == "www") {
+        let tld = toks.iter().take(4).position(|t| {
+            matches!(
+                t.low.as_str(),
+                "com" | "net" | "org" | "to" | "io" | "me" | "cc"
+            )
+        });
+        if let Some(i) = tld {
+            toks.drain(..=i);
+        }
+    }
+    while toks
+        .first()
+        .is_some_and(|t| !t.orig.is_empty() && t.orig.chars().all(|c| c == '-'))
+    {
+        toks.remove(0);
+    }
+}
+
+/// Group from a trailing dash: `x265-GROUP`, `TrueHD.7.1-FGT`, or the
+/// spaced form `... - GROUP`. Requires either a known marker left of the
+/// dash or a strong marker elsewhere, so `Spider-Man` alone keeps its dash.
+fn take_dash_group(toks: &mut Vec<Token>, has_strong: bool) -> Option<String> {
+    if toks.len() >= 2 && has_strong {
+        let sep = &toks[toks.len() - 2].orig;
+        let last = &toks[toks.len() - 1];
+        if !sep.is_empty() && sep.chars().all(|c| c == '-') && group_ok(&last.low) {
+            let g = last.orig.clone();
+            toks.truncate(toks.len() - 2);
+            return Some(g);
+        }
+    }
+    let last = toks.last()?;
+    if !last.orig.contains('-')
+        || markers::classify(&last.low).is_some()
+        || markers::is_season_episode(&last.low)
+    {
+        return None;
+    }
+    let (left, right) = last.orig.rsplit_once('-')?;
+    let left_low = left.to_lowercase();
+    let left_known = markers::classify(&left_low).is_some();
+    if !left.is_empty() && group_ok(&right.to_lowercase()) && (left_known || has_strong) {
+        let group = right.to_string();
+        let n = toks.len();
+        toks[n - 1] = Token {
+            orig: left.to_string(),
+            low: left_low,
+        };
+        return Some(group);
+    }
+    None
+}
+
+fn group_ok(low: &str) -> bool {
+    !low.is_empty()
+        && low.len() <= 24
+        && low.chars().any(|c| c.is_ascii_alphabetic())
+        && markers::classify(low).is_none()
+        && markers::year_of(low).is_none()
+        && !markers::is_season_episode(low)
+}
+
+/// Group from a trailing bracket tag, YTS style: `Movie (2024) [1080p]
+/// [YTS.MX]`. Bracketed chunks holding known markers are left in place for
+/// the token scan.
+fn take_trailing_bracket_group(s: &str) -> (String, Option<String>) {
+    const DENY: [&str; 4] = ["rartv", "eztv", "ettv", "tgx"];
+    let mut end = s.len();
+    loop {
+        let head = s[..end].trim_end_matches(|c: char| c.is_whitespace() || c == '.' || c == '-');
+        if !head.ends_with(']') {
+            break;
+        }
+        let Some(open) = head.rfind('[') else { break };
+        let content = &head[open + 1..head.len() - 1];
+        let low = content.to_lowercase();
+        let tokens_clean = low
+            .split(['.', '_', ' ', '-'])
+            .filter(|t| !t.is_empty())
+            .all(|t| {
+                markers::classify(t).is_none()
+                    && markers::year_of(t).is_none()
+                    && !markers::is_season_episode(t)
+            });
+        if !content.is_empty()
+            && !content.contains(' ')
+            && content.chars().any(|c| c.is_ascii_alphabetic())
+            && !DENY.contains(&low.as_str())
+            && tokens_clean
+        {
+            let mut out = String::with_capacity(s.len());
+            out.push_str(&s[..open]);
+            out.push_str(&s[head.len()..]);
+            return (out, Some(content.to_string()));
+        }
+        end = open;
+    }
+    (s.to_string(), None)
+}
+
+fn strip_extension(s: &str) -> &str {
+    if let Some((stem, ext)) = s.rsplit_once('.') {
+        let known = matches!(
+            ext.to_lowercase().as_str(),
+            "mkv"
+                | "mp4"
+                | "avi"
+                | "m4v"
+                | "mov"
+                | "wmv"
+                | "webm"
+                | "m2ts"
+                | "flv"
+                | "mpg"
+                | "mpeg"
+                | "iso"
+                | "divx"
+        );
+        if known && !stem.is_empty() {
+            return stem;
+        }
+    }
+    s
+}

crates/arr-parse/src/markers.rs

@@ -0,0 +1,204 @@
+//! Token classification tables. Input tokens are lowercase.
+
+use crate::{Codec, Edition, HdrMarker, LanguageMarker, Resolution, Source};
+
+/// What a recognised token claims. `Audio` and `Junk` are recognised so they
+/// anchor the title boundary and group detection, but are not surfaced.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum Marker {
+    Resolution(Resolution),
+    Source(Source),
+    Codec(Codec),
+    Hdr(HdrMarker),
+    Language(LanguageMarker),
+    Edition(Edition),
+    Audio,
+    Junk,
+}
+
+/// Strong markers set the title boundary. Weak markers are words that also
+/// occur in real titles ("Web", "Cam", "Dual") and only count once the
+/// boundary is already known.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum Strength {
+    Strong,
+    Weak,
+}
+
+pub(crate) fn classify(token: &str) -> Option<(Marker, Strength)> {
+    if let Some(m) = classify_exact(token) {
+        return Some(m);
+    }
+    if is_audio_family(token) {
+        return Some((Marker::Audio, Strength::Strong));
+    }
+    None
+}
+
+/// Two-token markers: `WEB DL`, `Dolby Vision`, `Dual Áudio`, `Directors Cut`.
+pub(crate) fn classify_pair(a: &str, b: &str) -> Option<(Marker, Strength)> {
+    let m = match (a, b) {
+        ("dolby", "vision") => (Marker::Hdr(HdrMarker::DolbyVision), Strength::Strong),
+        ("web", "dl") => (Marker::Source(Source::WebDl), Strength::Strong),
+        ("web", "rip") => (Marker::Source(Source::WebRip), Strength::Strong),
+        ("blu", "ray") => (Marker::Source(Source::BluRay), Strength::Strong),
+        ("dual", "audio" | "áudio") => (Marker::Language(LanguageMarker::Dual), Strength::Strong),
+        ("multi", "audio") => (Marker::Language(LanguageMarker::Multi), Strength::Strong),
+        ("h" | "x", "264") => (Marker::Codec(Codec::X264), Strength::Strong),
+        ("h" | "x", "265") => (Marker::Codec(Codec::X265), Strength::Strong),
+        ("directors" | "director's", "cut") => {
+            (Marker::Edition(Edition::DirectorsCut), Strength::Weak)
+        }
+        ("extended", "cut" | "edition") => (Marker::Edition(Edition::Extended), Strength::Weak),
+        ("special", "edition") => (Marker::Edition(Edition::SpecialEdition), Strength::Weak),
+        ("imax", "enhanced") => (Marker::Edition(Edition::Imax), Strength::Weak),
+        ("season", n) if !n.is_empty() && n.bytes().all(|c| c.is_ascii_digit()) => {
+            (Marker::Junk, Strength::Strong)
+        }
+        _ => return None,
+    };
+    Some(m)
+}
+
+#[allow(clippy::too_many_lines)]
+fn classify_exact(t: &str) -> Option<(Marker, Strength)> {
+    use Strength::{Strong, Weak};
+    let m = match t {
+        "2160p" | "4k" | "uhd" => (Marker::Resolution(Resolution::P2160), Strong),
+        "1080p" | "1080i" => (Marker::Resolution(Resolution::P1080), Strong),
+        "720p" => (Marker::Resolution(Resolution::P720), Strong),
+        "576p" | "576i" => (Marker::Resolution(Resolution::P576), Strong),
+        "480p" | "480i" => (Marker::Resolution(Resolution::P480), Strong),
+
+        "remux" | "bdremux" => (Marker::Source(Source::Remux), Strong),
+        "bluray" | "blu-ray" | "bdrip" | "brrip" => (Marker::Source(Source::BluRay), Strong),
+        "web-dl" | "webdl" => (Marker::Source(Source::WebDl), Strong),
+        "webrip" | "web-rip" => (Marker::Source(Source::WebRip), Strong),
+        "web" => (Marker::Source(Source::WebDl), Weak),
+        "hdtv" | "pdtv" => (Marker::Source(Source::Hdtv), Strong),
+        "dvdrip" | "dvd" => (Marker::Source(Source::Dvd), Strong),
+        "telesync" | "hdts" => (Marker::Source(Source::Telesync), Strong),
+        "ts" => (Marker::Source(Source::Telesync), Weak),
+        "telecine" | "hdtc" => (Marker::Source(Source::Telecine), Strong),
+        "tc" => (Marker::Source(Source::Telecine), Weak),
+        "screener" | "dvdscr" | "bdscr" => (Marker::Source(Source::Screener), Strong),
+        "scr" => (Marker::Source(Source::Screener), Weak),
+        "camrip" | "hdcam" => (Marker::Source(Source::Cam), Strong),
+        "cam" => (Marker::Source(Source::Cam), Weak),
+
+        "x264" | "h264" | "avc" => (Marker::Codec(Codec::X264), Strong),
+        "x265" | "h265" | "hevc" => (Marker::Codec(Codec::X265), Strong),
+        "av1" => (Marker::Codec(Codec::Av1), Strong),
+        "xvid" | "divx" => (Marker::Codec(Codec::Xvid), Strong),
+
+        "dovi" => (Marker::Hdr(HdrMarker::DolbyVision), Strong),
+        "dv" => (Marker::Hdr(HdrMarker::DolbyVision), Weak),
+        "hdr10+" | "hdr10plus" => (Marker::Hdr(HdrMarker::Hdr10Plus), Strong),
+        "hdr10" => (Marker::Hdr(HdrMarker::Hdr10), Strong),
+        "hdr" => (Marker::Hdr(HdrMarker::Hdr), Strong),
+        "hlg" => (Marker::Hdr(HdrMarker::Hlg), Strong),
+        "sdr" => (Marker::Hdr(HdrMarker::Sdr), Weak),
+
+        // pt-BR self-identification (`DESIGN.md` §5.2): loud and distinctive.
+        "pt-br" | "ptbr" | "dublado" | "nacional" => {
+            (Marker::Language(LanguageMarker::PtBr), Strong)
+        }
+        "pt-pt" | "ptpt" => (Marker::Language(LanguageMarker::PtPt), Strong),
+        "portuguese" | "português" | "portugues" => {
+            (Marker::Language(LanguageMarker::Portuguese), Strong)
+        }
+        "por" | "pt" => (Marker::Language(LanguageMarker::Portuguese), Weak),
+        "multi" => (Marker::Language(LanguageMarker::Multi), Strong),
+        "dual" => (Marker::Language(LanguageMarker::Dual), Weak),
+        "english" => (Marker::Language(LanguageMarker::English), Strong),
+        "eng" => (Marker::Language(LanguageMarker::English), Weak),
+        "french" | "truefrench" | "vostfr" => (Marker::Language(LanguageMarker::French), Strong),
+        "fre" | "fra" | "vf" | "vff" => (Marker::Language(LanguageMarker::French), Weak),
+        "german" | "deutsch" => (Marker::Language(LanguageMarker::German), Strong),
+        "ger" => (Marker::Language(LanguageMarker::German), Weak),
+        "spanish" | "castellano" | "latino" => (Marker::Language(LanguageMarker::Spanish), Strong),
+        "spa" | "esp" => (Marker::Language(LanguageMarker::Spanish), Weak),
+        "italian" | "italiano" => (Marker::Language(LanguageMarker::Italian), Strong),
+        "ita" => (Marker::Language(LanguageMarker::Italian), Weak),
+
+        "extended" => (Marker::Edition(Edition::Extended), Weak),
+        "unrated" => (Marker::Edition(Edition::Unrated), Weak),
+        "uncut" => (Marker::Edition(Edition::Uncut), Weak),
+        "theatrical" => (Marker::Edition(Edition::Theatrical), Weak),
+        "imax" => (Marker::Edition(Edition::Imax), Weak),
+        "remastered" => (Marker::Edition(Edition::Remastered), Weak),
+        "criterion" => (Marker::Edition(Edition::Criterion), Weak),
+        "limited" => (Marker::Edition(Edition::Limited), Weak),
+
+        "truehd" | "atmos" | "flac" | "opus" | "mp3" | "dd+" | "ma" => (Marker::Audio, Strong),
+
+        // "Legendado" claims pt-BR *subtitles* over original audio — it must
+        // NOT become a PtBr audio claim or main-root originals get rejected.
+        "proper" | "repack" | "internal" | "hybrid" | "10bit" | "8bit" | "hi10p" | "amzn"
+        | "dsnp" | "atvp" | "hmax" | "pcok" | "legendado" => (Marker::Junk, Strong),
+        "nf" | "hulu" | "max" | "itunes" | "cr" | "complete" | "sample" | "subbed" | "subs"
+        | "sub" | "mkv" | "mp4" | "avi" | "www" | "com" | "net" | "org" | "retail" | "readnfo" => {
+            (Marker::Junk, Weak)
+        }
+        _ => return None,
+    };
+    Some(m)
+}
+
+fn is_audio_family(t: &str) -> bool {
+    const PREFIXES: [&str; 9] = [
+        "ddp", "dd5", "dd7", "dd2", "dts", "eac3", "ac3", "aac", "truehd",
+    ];
+    PREFIXES.iter().any(|p| {
+        t.strip_prefix(p).is_some_and(|rest| {
+            matches!(rest, "-hd" | "hd" | "-x" | "x" | "-ma" | "ma" | "-hd-ma")
+                || rest
+                    .chars()
+                    .all(|c| c.is_ascii_digit() || matches!(c, '.' | '+' | '-'))
+        })
+    })
+}
+
+/// `S01`, `S01E02`, `S01E01E02`, `S01-E02`, `1x02`.
+pub(crate) fn is_season_episode(t: &str) -> bool {
+    fn digits(s: &str) -> (usize, &str) {
+        let n = s.bytes().take_while(u8::is_ascii_digit).count();
+        (n, &s[n..])
+    }
+    if let Some(rest) = t.strip_prefix('s') {
+        let (n, mut rest) = digits(rest);
+        if !(1..=2).contains(&n) {
+            return false;
+        }
+        while !rest.is_empty() {
+            let Some(r) = rest.strip_prefix('e').or_else(|| rest.strip_prefix("-e")) else {
+                return false;
+            };
+            let (m, r2) = digits(r);
+            if !(1..=3).contains(&m) {
+                return false;
+            }
+            rest = r2;
+        }
+        return true;
+    }
+    let (n, rest) = digits(t);
+    if (1..=2).contains(&n) {
+        if let Some(r) = rest.strip_prefix('x') {
+            let (m, r2) = digits(r);
+            return (2..=3).contains(&m) && r2.is_empty();
+        }
+    }
+    false
+}
+
+/// A plausible release year: four digits, 1900–2099.
+pub(crate) fn year_of(t: &str) -> Option<u16> {
+    if t.len() == 4 && t.bytes().all(|b| b.is_ascii_digit()) {
+        let y: u16 = t.parse().ok()?;
+        if (1900..=2099).contains(&y) {
+            return Some(y);
+        }
+    }
+    None
+}

crates/arr-parse/tests/parse.rs

@@ -0,0 +1,355 @@
+//! Table-driven checks over representative release names. The full fixture
+//! corpus pulled from real indexers is issue #9; these rows pin the parser's
+//! behaviour per shape of name.
+
+use arr_parse::{parse, Codec, Edition, HdrMarker, LanguageMarker, NameClaims, Resolution, Source};
+use serde as _;
+
+struct Case {
+    name: &'static str,
+    want: NameClaims,
+}
+
+#[allow(clippy::unnecessary_wraps)]
+fn s(v: &str) -> Option<String> {
+    Some(v.to_string())
+}
+
+#[allow(clippy::too_many_lines)]
+fn cases() -> Vec<Case> {
+    vec![
+        Case {
+            name: "Movie.Title.2024.2160p.UHD.BluRay.DV.HDR10.x265.TrueHD-GROUP",
+            want: NameClaims {
+                title: s("Movie Title"),
+                year: Some(2024),
+                resolution: Some(Resolution::P2160),
+                source: Some(Source::BluRay),
+                codec: Some(Codec::X265),
+                hdr: vec![HdrMarker::DolbyVision, HdrMarker::Hdr10],
+                group: s("GROUP"),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            // "Web" before the year is title, not a source claim.
+            name: "Charlottes.Web.2006.1080p.BluRay.x264-GRP",
+            want: NameClaims {
+                title: s("Charlottes Web"),
+                year: Some(2006),
+                resolution: Some(Resolution::P1080),
+                source: Some(Source::BluRay),
+                codec: Some(Codec::X264),
+                group: s("GRP"),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            name: "Dune Part Two (2024) [2160p] [WEB-DL] [HDR10+] [YTS.MX]",
+            want: NameClaims {
+                title: s("Dune Part Two"),
+                year: Some(2024),
+                resolution: Some(Resolution::P2160),
+                source: Some(Source::WebDl),
+                hdr: vec![HdrMarker::Hdr10Plus],
+                group: s("YTS.MX"),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            name: "O.Auto.da.Compadecida.2000.NACIONAL.1080p.WEB-DL.x264-BRA",
+            want: NameClaims {
+                title: s("O Auto da Compadecida"),
+                year: Some(2000),
+                resolution: Some(Resolution::P1080),
+                source: Some(Source::WebDl),
+                codec: Some(Codec::X264),
+                languages: vec![LanguageMarker::PtBr],
+                group: s("BRA"),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            // Repeated pt-BR markers dedupe to one claim.
+            name: "Filme.2023.Dublado.PT-BR.1080p.WEBRip.x264",
+            want: NameClaims {
+                title: s("Filme"),
+                year: Some(2023),
+                resolution: Some(Resolution::P1080),
+                source: Some(Source::WebRip),
+                codec: Some(Codec::X264),
+                languages: vec![LanguageMarker::PtBr],
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            name: "Filme.Infantil.2023.1080p.WEB-DL.Dual.Áudio.x264",
+            want: NameClaims {
+                title: s("Filme Infantil"),
+                year: Some(2023),
+                resolution: Some(Resolution::P1080),
+                source: Some(Source::WebDl),
+                codec: Some(Codec::X264),
+                languages: vec![LanguageMarker::Dual],
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            name: "Movie.2024.MULTi.1080p.WEB.x265-GRP",
+            want: NameClaims {
+                title: s("Movie"),
+                year: Some(2024),
+                resolution: Some(Resolution::P1080),
+                source: Some(Source::WebDl),
+                codec: Some(Codec::X265),
+                languages: vec![LanguageMarker::Multi],
+                group: s("GRP"),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            // Season/episode tags bound the title; no year needed.
+            name: "Serie.S01E02.720p.HDTV.x264-LOL",
+            want: NameClaims {
+                title: s("Serie"),
+                resolution: Some(Resolution::P720),
+                source: Some(Source::Hdtv),
+                codec: Some(Codec::X264),
+                group: s("LOL"),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            // Remux beats the BluRay marker riding along.
+            name: "Movie.2024.2160p.BluRay.REMUX.HEVC.TrueHD.7.1.Atmos-FGT",
+            want: NameClaims {
+                title: s("Movie"),
+                year: Some(2024),
+                resolution: Some(Resolution::P2160),
+                source: Some(Source::Remux),
+                codec: Some(Codec::X265),
+                group: s("FGT"),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            name: "Movie.2024.Extended.1080p.BluRay.x264",
+            want: NameClaims {
+                title: s("Movie"),
+                year: Some(2024),
+                resolution: Some(Resolution::P1080),
+                source: Some(Source::BluRay),
+                codec: Some(Codec::X264),
+                editions: vec![Edition::Extended],
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            // Edition between title and year is stripped off the title tail.
+            name: "Movie.Directors.Cut.2024.1080p.BluRay",
+            want: NameClaims {
+                title: s("Movie"),
+                year: Some(2024),
+                resolution: Some(Resolution::P1080),
+                source: Some(Source::BluRay),
+                editions: vec![Edition::DirectorsCut],
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            // First year-like token is the title, second is the year.
+            name: "2012.2009.1080p.BluRay.x264",
+            want: NameClaims {
+                title: s("2012"),
+                year: Some(2009),
+                resolution: Some(Resolution::P1080),
+                source: Some(Source::BluRay),
+                codec: Some(Codec::X264),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            name: "Blade.Runner.2049.2017.2160p.WEB-DL.DDP5.1.HDR.HEVC-XEBEC",
+            want: NameClaims {
+                title: s("Blade Runner 2049"),
+                year: Some(2017),
+                resolution: Some(Resolution::P2160),
+                source: Some(Source::WebDl),
+                codec: Some(Codec::X265),
+                hdr: vec![HdrMarker::Hdr],
+                group: s("XEBEC"),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            name: "Movie.2024.HDTS.x264-ETRG",
+            want: NameClaims {
+                title: s("Movie"),
+                year: Some(2024),
+                source: Some(Source::Telesync),
+                codec: Some(Codec::X264),
+                group: s("ETRG"),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            name: "Movie.2024.1080p.HMAX.WEB-DL.DD5.1.H.264-GROUP",
+            want: NameClaims {
+                title: s("Movie"),
+                year: Some(2024),
+                resolution: Some(Resolution::P1080),
+                source: Some(Source::WebDl),
+                codec: Some(Codec::X264),
+                group: s("GROUP"),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            // Spaced dash before the group.
+            name: "Movie Title 2024 1080p BluRay x265 - VXT",
+            want: NameClaims {
+                title: s("Movie Title"),
+                year: Some(2024),
+                resolution: Some(Resolution::P1080),
+                source: Some(Source::BluRay),
+                codec: Some(Codec::X265),
+                group: s("VXT"),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            // Filename with a container extension.
+            name: "Movie.Title.2024.720p.WEBRip.x264.mkv",
+            want: NameClaims {
+                title: s("Movie Title"),
+                year: Some(2024),
+                resolution: Some(Resolution::P720),
+                source: Some(Source::WebRip),
+                codec: Some(Codec::X264),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            // No markers at all: the whole thing is a title claim.
+            name: "Some Random Words",
+            want: NameClaims {
+                title: s("Some Random Words"),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            // Marker-only garbage parses partially, title absent.
+            name: "1080p",
+            want: NameClaims {
+                resolution: Some(Resolution::P1080),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            name: "",
+            want: NameClaims::default(),
+        },
+        Case {
+            // Dolby Vision spelled out, dotted.
+            name: "Movie.2024.2160p.WEB-DL.Dolby.Vision.HDR10.HEVC-GRP",
+            want: NameClaims {
+                title: s("Movie"),
+                year: Some(2024),
+                resolution: Some(Resolution::P2160),
+                source: Some(Source::WebDl),
+                codec: Some(Codec::X265),
+                hdr: vec![HdrMarker::DolbyVision, HdrMarker::Hdr10],
+                group: s("GRP"),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            // Hyphenated title survives when nothing marks a group.
+            name: "Spider-Man.2002.1080p.BluRay.x264-SECTOR7",
+            want: NameClaims {
+                title: s("Spider-Man"),
+                year: Some(2002),
+                resolution: Some(Resolution::P1080),
+                source: Some(Source::BluRay),
+                codec: Some(Codec::X264),
+                group: s("SECTOR7"),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            name: "www.Torrenting.com - Movie.2024.1080p.WEB-DL.x264",
+            want: NameClaims {
+                title: s("Movie"),
+                year: Some(2024),
+                resolution: Some(Resolution::P1080),
+                source: Some(Source::WebDl),
+                codec: Some(Codec::X264),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            // Season pack, no episode.
+            name: "Show.Name.S02.2160p.WEB-DL.DDP5.1.DV.HDR10.H.265-NTb",
+            want: NameClaims {
+                title: s("Show Name"),
+                resolution: Some(Resolution::P2160),
+                source: Some(Source::WebDl),
+                codec: Some(Codec::X265),
+                hdr: vec![HdrMarker::DolbyVision, HdrMarker::Hdr10],
+                group: s("NTb"),
+                ..NameClaims::default()
+            },
+        },
+        Case {
+            name: "Movie.2019.4K.HDR.DV.2160p.BDRemux.Ita.Eng.x265-NAHOM",
+            want: NameClaims {
+                title: s("Movie"),
+                year: Some(2019),
+                resolution: Some(Resolution::P2160),
+                source: Some(Source::Remux),
+                codec: Some(Codec::X265),
+                hdr: vec![HdrMarker::Hdr, HdrMarker::DolbyVision],
+                languages: vec![LanguageMarker::Italian, LanguageMarker::English],
+                group: s("NAHOM"),
+                ..NameClaims::default()
+            },
+        },
+    ]
+}
+
+#[test]
+fn corpus_rows_parse_as_expected() {
+    let mut failures = Vec::new();
+    for Case { name, want } in cases() {
+        let got = parse(name);
+        if got != want {
+            failures.push(format!("{name:?}\n  got:  {got:?}\n  want: {want:?}"));
+        }
+    }
+    assert!(
+        failures.is_empty(),
+        "{} mismatches:\n{}",
+        failures.len(),
+        failures.join("\n")
+    );
+}
+
+#[test]
+fn garbage_never_panics() {
+    let inputs = [
+        "",
+        " ",
+        "....",
+        "----",
+        "[[[]]]",
+        "()()()",
+        "ção áéíóú 日本語 🎬🎬🎬",
+        "-.-.-.-[]()s01e999999999999999999999",
+        "Movie.2024.1080p-",
+        "a",
+        &"x.".repeat(5000),
+    ];
+    for input in inputs {
+        let _ = parse(input);
+    }
+}