feat(meta): TMDB search and movie lookup (#49)

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())
+}