491 lines
18 KiB
Rust
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", ¶ms).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, ¶ms).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, ¶ms).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, ¶ms).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", ¶ms).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, ¶ms).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, ¶ms).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, ¶ms).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()))
|
|
}
|