Files
arr/crates/arr-meta/src/client.rs
T

491 lines
18 KiB
Rust

//! The TMDB HTTP client.
use std::path::PathBuf;
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::Duration;
use reqwest::{StatusCode, Url};
use serde::de::DeserializeOwned;
use crate::cache::Cache;
use crate::error::{Error, Result};
use crate::model::{
select_trailer, ExternalIds, FindResults, Movie, MovieDetail, MovieSearchResult,
RawExternalIds, RawFindPage, RawMovie, RawMovieDetail, RawSearchPage, RawSeason, RawSeries,
RawSeriesDetail, RawSeriesSearchPage, RawVideoList, Season, Series, SeriesDetail,
SeriesSearchResult, Video,
};
/// 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);
/// 64 MiB. Dokploy's samples for `arr.n62.casa` showed resident memory going
/// from 16.1-16.5 MiB to 48.77 MiB across the TV-tracking and rich-metadata
/// milestones (issue #158) — roughly 32 MiB of growth attributable to the
/// same cache this now bounds, on one household's ordinary usage. Doubling
/// that for a busier day, and rounding up, gives a ceiling that is real —
/// unlike the memory it replaces — without being tight; `DEFAULT_CACHE_TTL`
/// clears the whole directory every day regardless.
pub const DEFAULT_CACHE_MAX_BYTES: u64 = 64 * 1024 * 1024;
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 on-disk 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,
cache_dir: None,
cache_max_bytes: DEFAULT_CACHE_MAX_BYTES,
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())
}
/// Resolve an `IMDb` title id through TMDB's external-id index.
///
/// TMDB answers with both kinds in one response, so one call surfaces
/// whichever the id names — the way a raw TMDB id resolves (§9.2).
///
/// # Errors
///
/// Any of [`Error`]; see its variants for what callers should distinguish.
pub async fn find_by_imdb(&self, imdb_id: &str) -> Result<FindResults> {
let path = format!("find/{}", imdb_id.trim());
let params = [("external_source", "imdb_id".to_owned())];
let page: RawFindPage = self.get_json(&path, &params).await?;
Ok(FindResults {
movies: page.movie_results.into_iter().map(Into::into).collect(),
series: page.tv_results.into_iter().map(Into::into).collect(),
})
}
/// Resolve a TVDB series id through TMDB's external-id index.
///
/// # Errors
///
/// Any of [`Error`]; see its variants for what callers should distinguish.
pub async fn find_series_by_tvdb(&self, tvdb_id: u32) -> Result<Vec<SeriesSearchResult>> {
let path = format!("find/{tvdb_id}");
let params = [("external_source", "tvdb_id".to_owned())];
let page: RawFindPage = self.get_json(&path, &params).await?;
Ok(page.tv_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())
}
/// Search TMDB for TV series by title.
///
/// # Errors
///
/// Any of [`Error`]; see its variants for what callers should distinguish.
pub async fn search_series(&self, query: &str) -> Result<Vec<SeriesSearchResult>> {
let params = [
("query", query.trim().to_owned()),
("include_adult", "false".to_owned()),
];
let page: RawSeriesSearchPage = self.get_json("search/tv", &params).await?;
Ok(page.results.into_iter().map(Into::into).collect())
}
/// Full detail for one TV series, including its season summaries.
///
/// # Errors
///
/// [`Error::NotFound`] when TMDB has no such id, otherwise any of [`Error`].
pub async fn series(&self, tmdb_id: u32) -> Result<Series> {
let path = format!("tv/{tmdb_id}");
let params = [("append_to_response", "external_ids".to_owned())];
let raw: RawSeries = self.get_json(&path, &params).await?;
Ok(raw.into())
}
/// Rich detail for one movie's §9.6 page.
///
/// One HTTP call: credits, videos and external ids come back appended to
/// the same response. Served through the same cache as [`Self::movie`];
/// nothing here is persisted (§9.6).
///
/// # Errors
///
/// [`Error::NotFound`] when TMDB has no such id, otherwise any of [`Error`].
pub async fn movie_detail(&self, tmdb_id: u32) -> Result<MovieDetail> {
let path = format!("movie/{tmdb_id}");
let params = [(
"append_to_response",
"credits,videos,external_ids".to_owned(),
)];
let raw: RawMovieDetail = self.get_json(&path, &params).await?;
Ok(raw.into())
}
/// Rich detail for one series' §9.6 page.
///
/// # Errors
///
/// [`Error::NotFound`] when TMDB has no such id, otherwise any of [`Error`].
pub async fn series_detail(&self, tmdb_id: u32) -> Result<SeriesDetail> {
let path = format!("tv/{tmdb_id}");
let params = [(
"append_to_response",
"credits,videos,external_ids".to_owned(),
)];
let raw: RawSeriesDetail = self.get_json(&path, &params).await?;
Ok(raw.into())
}
/// The chosen trailer for a movie, fetching only the videos list.
///
/// #144's search-row chip resolves through this, where a full detail
/// response would be waste (§9.6).
///
/// # Errors
///
/// [`Error::NotFound`] when TMDB has no such id, otherwise any of [`Error`].
pub async fn movie_videos(&self, tmdb_id: u32) -> Result<Option<Video>> {
let path = format!("movie/{tmdb_id}/videos");
let raw: RawVideoList = self.get_json(&path, &[]).await?;
Ok(select_trailer(&raw.into_videos()))
}
/// The chosen trailer for a series, fetching only the videos list.
///
/// # Errors
///
/// [`Error::NotFound`] when TMDB has no such id, otherwise any of [`Error`].
pub async fn series_videos(&self, tmdb_id: u32) -> Result<Option<Video>> {
let path = format!("tv/{tmdb_id}/videos");
let raw: RawVideoList = self.get_json(&path, &[]).await?;
Ok(select_trailer(&raw.into_videos()))
}
/// External ids for one TV series, of which the TVDB id is the one this
/// project needs (§6.1).
///
/// # Errors
///
/// [`Error::NotFound`] when TMDB has no such id, otherwise any of [`Error`].
pub async fn series_external_ids(&self, tmdb_id: u32) -> Result<ExternalIds> {
let path = format!("tv/{tmdb_id}/external_ids");
let raw: RawExternalIds = self.get_json(&path, &[]).await?;
Ok(ExternalIds {
tvdb_id: raw.tvdb_id,
})
}
/// Episodes in one TV season.
///
/// # Errors
///
/// [`Error::NotFound`] when TMDB has no such season, otherwise any of [`Error`].
pub async fn season(&self, tmdb_id: u32, season_number: u32) -> Result<Season> {
let path = format!("tv/{tmdb_id}/season/{season_number}");
let raw: RawSeason = self.get_json(&path, &[]).await?;
Ok(raw.into())
}
/// Drop every cached response. For a user-initiated "refresh metadata".
pub fn clear_cache(&self) {
self.cache.clear();
}
/// Evict expired cache entries, and the oldest survivors if the
/// directory is still over its size budget. `insert` already does this
/// after every write, so calling this is only needed to reclaim space an
/// idle cache is sitting on — the daily metadata tick (§8) is the
/// intended caller.
pub fn sweep_cache(&self) {
self.cache.sweep();
}
/// 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, &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,
cache_dir: Option<PathBuf>,
cache_max_bytes: u64,
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
}
/// Where cache files live.
///
/// Left unset, `build` picks a process-unique directory under the OS
/// temp dir and removes it when the client is dropped — a warm cache
/// never outlives one process, same as before this cache moved to disk.
/// Production wants this pointed explicitly at a directory alongside the
/// database (DESIGN.md §10), from bootstrap config, so a restart keeps a
/// warm cache; a directory set this way is the caller's and is left
/// alone on drop.
#[must_use]
pub fn cache_dir(mut self, cache_dir: impl Into<PathBuf>) -> Self {
self.cache_dir = Some(cache_dir.into());
self
}
/// Upper bound on total cache size in bytes, enforced by evicting the
/// oldest entries first. See [`DEFAULT_CACHE_MAX_BYTES`] for how the
/// default was chosen.
#[must_use]
pub fn cache_max_bytes(mut self, cache_max_bytes: u64) -> Self {
self.cache_max_bytes = cache_max_bytes;
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, [`Error::Cache`] if the cache
/// directory cannot be created.
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()?;
let (cache_dir, owns_cache_dir) = match self.cache_dir {
Some(dir) => (dir, false),
None => (default_cache_dir(), true),
};
let cache = Cache::new(
cache_dir,
self.cache_ttl,
self.cache_max_bytes,
owns_cache_dir,
)?;
Ok(TmdbClient {
http,
base_url,
api_key: self.api_key,
cache,
})
}
}
/// A process-unique directory under the OS temp dir, used when the caller
/// does not configure `cache_dir` explicitly. Unique per built client (not
/// just per process) so that tests building several clients in the same
/// process, against the same TMDB paths but different mock responses, do not
/// share a cache and see each other's bodies.
fn default_cache_dir() -> PathBuf {
static COUNTER: AtomicU64 = AtomicU64::new(0);
let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
std::env::temp_dir().join(format!("arr-meta-cache-{}-{unique}", std::process::id()))
}