//! Request handling of the podcast UI and the web player. //! //! [`super::http`] authenticates the request and passes the account here. //! Every function takes the store, the account and the decoded input and //! returns a JSON view or an [`ApiError`] with its HTTP status, so the //! behavior of the endpoints is testable without an HTTP server //! (`postgres_tests`). //! //! Playback follows the progress rules of the frid podcast contract //! (`PODCASTS.md`, "Progress" and "Listening sessions and counts"): //! //! * [`playback`] prepares an episode for the player: the audio source, the //! position ordinary Play resumes from and, when the browser starts //! playing (`start`), a new listening session written as an explicit //! action (`explicit_generation(max(local, carried))`). //! * [`progress`] stores what the player reports for that session: periodic //! checkpoints and pause/stop/handoff saves keep the session generation, a //! user seek is an explicit action, the end of the stream or //! `reaches_completion` completes the episode once, and the listening //! session is recorded (history counts only completed sessions). use music_dht::device_sync::PlaybackTrack; use music_dht::podcast::{ EpisodeId, EpisodeType, FeedUrl, ListenSession, PodcastEpisodeRef, PodcastId, PodcastMeta, ProgressRecord, ProgressStatus, reaches_completion, }; use music_dht::podcast_dht::{FeedUrlPrivacyWarning, PodcastDht}; use serde::{Deserialize, Serialize}; use serde_json::Value; use super::fetch::{FeedFetch, FeedFetcher, FetchErrorKind}; use super::runner::{self, SubscribeUrlError}; use super::search; use super::{ CheckpointOutcome, EpisodeListItem, EpisodeQuery, EpisodeSort, FetchState, PlayedFilter, PodcastListFilter, PodcastStore, PodcastStoreError, PodcastSummary, ProgressSession, SeasonFilter, SeasonSummary, }; use crate::federation::devices; use crate::player::queue_items; /// Episodes per page when the request does not say. pub(crate) const DEFAULT_EPISODE_PAGE: usize = 50; /// Largest episode page. pub(crate) const MAX_EPISODE_PAGE: usize = 200; /// A failed request: HTTP status and a message for the user. #[derive(Debug, Clone, PartialEq, Eq)] pub(crate) struct ApiError { pub(crate) status: u16, pub(crate) message: String, } impl ApiError { pub(crate) fn new(status: u16, message: impl Into) -> Self { Self { status, message: message.into(), } } fn bad_request(message: impl Into) -> Self { Self::new(400, message) } fn not_found(message: impl Into) -> Self { Self::new(404, message) } } impl From for ApiError { fn from(error: anyhow::Error) -> Self { if let Some(error) = error.downcast_ref::() { return match error { PodcastStoreError::UnknownPodcast(_) => Self::not_found(error.to_string()), PodcastStoreError::NotSubscribed(_) => Self::new(409, error.to_string()), PodcastStoreError::Invalid(_) => Self::bad_request(error.to_string()), PodcastStoreError::SubscriptionLimit(_) | PodcastStoreError::ReferenceLimit(_) => { Self::new(422, error.to_string()) } }; } if let Some(SubscribeUrlError::Fetch(fetch)) = error.downcast_ref::() { // The feed could not be used: the request cannot succeed as is. let status = match fetch.kind { FetchErrorKind::Timeout | FetchErrorKind::Transport => 502, _ => 422, }; // The user sees the kind of failure only (no resolved // addresses or transport details); the log keeps the details. tracing::info!("podcast feed could not be added: {}", fetch.message); return Self::new(status, error.to_string()); } tracing::warn!("podcast API request failed: {error:#}"); Self::new(500, "internal error") } } pub(crate) type ApiResult = Result; pub(crate) fn parse_podcast_id(value: &str) -> ApiResult { PodcastId::parse(value).map_err(|_| ApiError::bad_request("invalid podcast id")) } pub(crate) fn parse_episode_id(value: &str) -> ApiResult { EpisodeId::parse(value).map_err(|_| ApiError::bad_request("invalid episode id")) } fn decode(body: Value) -> ApiResult { serde_json::from_value(body).map_err(|error| ApiError::bad_request(error.to_string())) } fn status_name(status: ProgressStatus) -> &'static str { match status { ProgressStatus::NotStarted => "not_started", ProgressStatus::InProgress => "in_progress", ProgressStatus::Completed => "completed", } } fn episode_type_name(kind: EpisodeType) -> &'static str { match kind { EpisodeType::Full => "full", EpisodeType::Trailer => "trailer", EpisodeType::Bonus => "bonus", } } // --------------------------------------------------------------------------- // Views // --------------------------------------------------------------------------- /// Local fetch state shown next to a podcast (never synced). #[derive(Debug, Clone, Serialize)] pub(crate) struct FetchView { pub(crate) checked_at_ms: Option, pub(crate) last_success_at_ms: Option, pub(crate) next_check_at_ms: Option, pub(crate) last_error: Option, pub(crate) consecutive_failures: u32, } impl From for FetchView { fn from(state: FetchState) -> Self { Self { checked_at_ms: state.checked_at_ms, last_success_at_ms: state.last_success_at_ms, next_check_at_ms: state.next_check_at_ms, last_error: state.last_error, consecutive_failures: state.consecutive_failures, } } } /// A podcast with its personal state and counters. #[derive(Debug, Clone, Serialize)] pub(crate) struct PodcastView { pub(crate) podcast_id: String, /// URL this account fetches. pub(crate) feed_url: String, pub(crate) title: String, pub(crate) author: Option, pub(crate) description: Option, pub(crate) link: Option, pub(crate) image_url: Option, pub(crate) subscribed: bool, /// The account's synced share decision applies (`effective_share`). /// Whether the card is actually published is [`ShareView`]. pub(crate) shared: bool, pub(crate) episode_count: u64, pub(crate) unplayed_count: u64, pub(crate) in_progress_count: u64, pub(crate) season_count: u64, pub(crate) latest_published_at_ms: Option, pub(crate) fetch: FetchView, } impl PodcastView { fn new(summary: PodcastSummary, fetch: FetchState) -> Self { Self { podcast_id: summary.podcast_id.to_string(), feed_url: summary.meta.feed_url.to_string(), title: summary.meta.title, author: summary.meta.author, description: summary.meta.description, link: summary.meta.link, image_url: summary.meta.image_url, subscribed: summary.subscribed, shared: summary.shared, episode_count: summary.episode_count, unplayed_count: summary.unplayed_count, in_progress_count: summary.in_progress_count, season_count: summary.season_count, latest_published_at_ms: summary.latest_published_at_ms, fetch: fetch.into(), } } } /// One season group (`season: null` holds the episodes without a season). #[derive(Debug, Clone, Serialize)] pub(crate) struct SeasonView { pub(crate) season: Option, pub(crate) episode_count: u64, pub(crate) unplayed_count: u64, pub(crate) first_published_at_ms: Option, pub(crate) last_published_at_ms: Option, } impl From for SeasonView { fn from(season: SeasonSummary) -> Self { Self { season: season.season, episode_count: season.episode_count, unplayed_count: season.unplayed_count, first_published_at_ms: season.first_published_at_ms, last_published_at_ms: season.last_published_at_ms, } } } /// An episode with its progress and the queue item the player uses. #[derive(Debug, Clone, Serialize)] pub(crate) struct EpisodeView { pub(crate) episode_id: String, pub(crate) podcast_id: String, pub(crate) title: String, pub(crate) description: Option, pub(crate) season: Option, pub(crate) episode_number: Option, pub(crate) episode_type: &'static str, pub(crate) published_at_ms: Option, pub(crate) duration_ms: Option, pub(crate) image_url: Option, pub(crate) link: Option, /// Whether the latest refresh listed the episode (older episodes stay). pub(crate) in_feed: bool, /// `not_started`, `in_progress` or `completed`. pub(crate) status: &'static str, /// Stored position of the progress register. pub(crate) position_ms: i64, /// Where ordinary Play resumes (`ProgressRecord::resume_position_ms`). pub(crate) resume_position_ms: i64, /// Distinct completed listening sessions. pub(crate) completed_count: u64, /// Browser queue item: `PlaybackSource::PodcastEpisode` with the /// self-contained reference (see `player::queue_items`). pub(crate) track: Value, } /// The queue reference of a catalog episode, with the register generation /// as handoff hint. fn episode_ref(item: &EpisodeListItem, podcast: &PodcastMeta) -> PodcastEpisodeRef { let mut reference = item.episode.to_ref(podcast); reference.progress_generation = item.progress.as_ref().map(|record| record.generation); reference } /// Browser queue item of an episode reference. pub(crate) fn episode_track_json(reference: PodcastEpisodeRef) -> Value { queue_items::external_track_json(&PlaybackTrack::podcast_episode(reference), 0, None) } impl EpisodeView { fn new(item: EpisodeListItem, podcast: &PodcastMeta) -> Self { let track = episode_track_json(episode_ref(&item, podcast)); let status = status_name(item.status()); let resume_position_ms = item.resume_position_ms(); let position_ms = item .progress .as_ref() .map_or(0, |progress| progress.position_ms); let episode = item.episode; Self { episode_id: episode.episode_id.to_string(), podcast_id: episode.podcast_id.to_string(), title: episode.title, description: episode.description, season: episode.season, episode_number: episode.episode_number, episode_type: episode_type_name(episode.episode_type), published_at_ms: episode.published_at_ms, duration_ms: episode.duration_ms, image_url: episode.image_url, link: episode.link, in_feed: item.in_feed, status, position_ms, resume_position_ms, completed_count: item.completed_count, track, } } } async fn podcast_view( store: &PodcastStore, user_id: i64, podcast_id: &PodcastId, ) -> ApiResult { let summary = store .podcast(user_id, podcast_id) .await? .ok_or_else(|| ApiError::not_found("unknown podcast"))?; let fetch = store.fetch_state(user_id, podcast_id).await?; Ok(PodcastView::new(summary, fetch)) } async fn episode_view( store: &PodcastStore, user_id: i64, episode_id: &EpisodeId, ) -> ApiResult { let item = store .episode(user_id, episode_id) .await? .ok_or_else(|| ApiError::not_found("unknown episode"))?; let podcast = store .podcast(user_id, &item.episode.podcast_id) .await? .ok_or_else(|| ApiError::not_found("unknown podcast"))?; Ok(EpisodeView::new(item, &podcast.meta)) } async fn catalog_ref( store: &PodcastStore, user_id: i64, episode_id: &EpisodeId, ) -> ApiResult { store .episode_ref(user_id, episode_id) .await? .ok_or_else(|| ApiError::not_found("unknown episode")) } // --------------------------------------------------------------------------- // Podcasts // --------------------------------------------------------------------------- #[derive(Debug, Serialize)] pub(crate) struct PodcastList { pub(crate) podcasts: Vec, } /// Podcasts of the account: subscribed ones, or with `all` also /// unsubscribed podcasts and podcasts only known from synced progress. pub(crate) async fn list_podcasts( store: &PodcastStore, user_id: i64, all: bool, ) -> ApiResult { let filter = if all { PodcastListFilter::All } else { PodcastListFilter::Subscribed }; let mut podcasts = Vec::new(); for summary in store.list_podcasts(user_id, filter).await? { let fetch = store.fetch_state(user_id, &summary.podcast_id).await?; podcasts.push(PodcastView::new(summary, fetch)); } Ok(PodcastList { podcasts }) } /// Listening sessions shown in a podcast's history. pub(crate) const DETAIL_HISTORY_LIMIT: usize = 20; /// A listening session in the history (completed or at least 30 s). #[derive(Debug, Clone, Serialize)] pub(crate) struct HistoryView { pub(crate) episode_id: String, pub(crate) episode_title: Option, pub(crate) started_at_ms: i64, pub(crate) ended_at_ms: i64, pub(crate) listened_ms: i64, pub(crate) completed: bool, } #[derive(Debug, Serialize)] pub(crate) struct PodcastDetail { pub(crate) podcast: PodcastView, /// Public discovery state of the podcast for this account. pub(crate) share: ShareView, pub(crate) seasons: Vec, /// Newest listening sessions of this podcast, from every device. pub(crate) history: Vec, } /// One podcast with its season groups and its public discovery state /// (`discovery`: the server's overlay, when it runs). pub(crate) async fn podcast_detail( store: &PodcastStore, user_id: i64, podcast_id: &PodcastId, discovery: Option<&PodcastDht>, ) -> ApiResult { let podcast = podcast_view(store, user_id, podcast_id).await?; let share = share_view(store, user_id, podcast_id, discovery).await?; let seasons = store .seasons(user_id, podcast_id) .await? .into_iter() .map(SeasonView::from) .collect(); let history = store .listen_history(user_id, Some(podcast_id), DETAIL_HISTORY_LIMIT) .await? .into_iter() .map(|entry| HistoryView { episode_id: entry.session.episode_id.to_string(), episode_title: entry.episode_title, started_at_ms: entry.session.started_at_ms, ended_at_ms: entry.session.ended_at_ms, listened_ms: entry.session.listened_ms, completed: entry.session.completed, }) .collect(); Ok(PodcastDetail { podcast, share, seasons, history, }) } #[derive(Debug, Deserialize)] struct SubscribeRequest { url: String, } #[derive(Debug, Serialize)] pub(crate) struct SubscribeResponse { pub(crate) podcast: PodcastView, pub(crate) already_subscribed: bool, pub(crate) new_episodes: usize, } /// "Add RSS": `{ "url": "..." }`. The feed is fetched before anything is /// stored; the new subscription is private. pub(crate) async fn subscribe_url( store: &PodcastStore, fetcher: &FeedFetcher, user_id: i64, body: Value, now_ms: i64, ) -> ApiResult { let request: SubscribeRequest = decode(body)?; let url = FeedUrl::from_user_input(&request.url) .map_err(|error| ApiError::bad_request(format!("invalid feed URL: {error}")))?; let subscription = runner::subscribe_url(store, fetcher, user_id, &url, now_ms).await?; Ok(SubscribeResponse { podcast: podcast_view(store, user_id, &subscription.podcast_id).await?, already_subscribed: subscription.already_subscribed, new_episodes: subscription.refresh.new_episodes, }) } /// Subscribes again to a known podcast with its stored channel metadata /// (progress and history continue). The refresh job fetches it on its next /// run. pub(crate) async fn resubscribe( store: &PodcastStore, user_id: i64, podcast_id: &PodcastId, ) -> ApiResult { let summary = store .podcast(user_id, podcast_id) .await? .ok_or_else(|| ApiError::not_found("unknown podcast"))?; store.subscribe(user_id, &summary.meta).await?; podcast_view(store, user_id, podcast_id).await } /// Unsubscribes: stops monitoring, revokes a publication, keeps progress /// and history. pub(crate) async fn unsubscribe( store: &PodcastStore, user_id: i64, podcast_id: &PodcastId, ) -> ApiResult { if store.podcast(user_id, podcast_id).await?.is_none() { return Err(ApiError::not_found("unknown podcast")); } store.unsubscribe(user_id, podcast_id).await?; podcast_view(store, user_id, podcast_id).await } // --------------------------------------------------------------------------- // Sharing (public discovery) // --------------------------------------------------------------------------- /// Public discovery state of one podcast for the signed-in account. /// /// Sharing is the account's synced decision; the card is published by the /// server's federation node (see [`super::discovery`]) and contains only /// the podcast's public metadata. #[derive(Debug, Clone, Serialize)] pub(crate) struct ShareView { /// The account's share decision applies (`effective_share`). pub(crate) shared: bool, /// Shared, but the card's privacy warnings are not confirmed by this /// account for the current decision and URLs: not published for it. pub(crate) pending_confirmation: bool, /// Whether the account can share the podcast now (subscribed and the /// card can be built). pub(crate) can_share: bool, /// Why the card cannot be built, if it cannot. pub(crate) card_error: Option, /// Why the card's feed URLs may be private (`PodcastCardSpec:: /// privacy_warnings`); enabling sharing must be confirmed when present. pub(crate) warnings: Vec, /// Feed URL the card would publish. pub(crate) feed_url: Option, /// Origin URL the podcast id comes from, when the feed moved. pub(crate) id_feed_url: Option, /// `running` when the server's node runs public discovery, `off` /// otherwise (federation disabled or the overlay failed to start). pub(crate) discovery: &'static str, /// The server currently publishes a card of this podcast and this /// account shares it. pub(crate) published: bool, } /// The account's [`ShareView`] of a podcast. pub(crate) async fn share_view( store: &PodcastStore, user_id: i64, podcast_id: &PodcastId, discovery: Option<&PodcastDht>, ) -> ApiResult { let account = store.account_share(user_id, podcast_id).await?; let mut view = ShareView { shared: false, pending_confirmation: false, can_share: false, card_error: None, warnings: Vec::new(), feed_url: None, id_feed_url: None, discovery: if discovery.is_some() { "running" } else { "off" }, published: false, }; let Some(account) = account else { return Ok(view); }; view.shared = account.is_shared(); view.pending_confirmation = account.pending_confirmation(); view.warnings = account.warnings(); match &account.card { Ok(card) => { view.can_share = account.subscription.subscribed; view.feed_url = Some(card.feed_url.to_string()); view.id_feed_url = card.id_feed_url.as_ref().map(ToString::to_string); } Err(error) => view.card_error = Some(error.clone()), } if let Some(dht) = discovery && account.publishable() { view.published = dht .published() .await .map_err(|error| anyhow::anyhow!("podcast publications unavailable: {error}"))? .iter() .any(|publication| publication.active && publication.podcast_id == *podcast_id); } Ok(view) } /// URLs the user confirmed in the privacy dialog. #[derive(Debug, Clone, Deserialize)] pub(crate) struct ShareConfirmRequest { pub(crate) feed_url: String, #[serde(default)] pub(crate) id_feed_url: Option, } #[derive(Debug, Clone, Deserialize)] struct ShareRequest { shared: bool, /// Confirmation of the card's URLs despite its privacy warnings. #[serde(default)] confirm: Option, } #[derive(Debug, Serialize)] pub(crate) struct ShareResponse { pub(crate) podcast: PodcastView, pub(crate) share: ShareView, } /// Result of [`set_share`]. #[derive(Debug)] pub(crate) enum ShareOutcome { /// The decision is stored (or was already in place). Done(Box), /// The card's feed URLs look private: nothing was written; ask the user /// and send the shown URLs back as `confirm` (HTTP 409). NeedsConfirmation(ShareView), } /// "Share in the federation": `{ "shared": bool, "confirm"?: {feed_url, /// id_feed_url} }`. /// /// * Off: writes `shared = false` (no-op when not shared) and forgets the /// confirmation; the reconciler revokes the card unless another account /// still shares the podcast. /// * On: needs an active subscription (409). When the card has privacy /// warnings, `confirm` must name exactly the card's current URLs; /// otherwise nothing is written and [`ShareOutcome::NeedsConfirmation`] /// carries the warnings. A podcast already shared from another device /// but pending this account's confirmation is confirmed the same way. pub(crate) async fn set_share( store: &PodcastStore, user_id: i64, podcast_id: &PodcastId, body: Value, discovery: Option<&PodcastDht>, now_ms: i64, ) -> ApiResult { let request: ShareRequest = decode(body)?; if store.podcast(user_id, podcast_id).await?.is_none() { return Err(ApiError::not_found("unknown podcast")); } if request.shared { let Some(account) = store.account_share(user_id, podcast_id).await? else { return Err( anyhow::Error::from(PodcastStoreError::NotSubscribed(podcast_id.clone())).into(), ); }; if !account.subscription.subscribed { return Err( anyhow::Error::from(PodcastStoreError::NotSubscribed(podcast_id.clone())).into(), ); } if let Err(error) = &account.card { return Err(ApiError::new( 422, format!("this podcast cannot be published: {error}"), )); } if account.warnings().is_empty() { store.set_shared(user_id, podcast_id, true).await?; } else { let confirmed = match &request.confirm { Some(confirm) => { let parse = |url: &str| { FeedUrl::parse(url) .map_err(|_| ApiError::bad_request("invalid confirmed feed URL")) }; let feed_url = parse(&confirm.feed_url)?; let id_feed_url = confirm.id_feed_url.as_deref().map(parse).transpose()?; store .share_confirmed( user_id, podcast_id, &feed_url, id_feed_url.as_ref(), now_ms, ) .await? .is_some() } None => false, }; if !confirmed { let view = share_view(store, user_id, podcast_id, discovery).await?; return Ok(ShareOutcome::NeedsConfirmation(view)); } } } else { store.set_shared(user_id, podcast_id, false).await?; store.clear_share_confirmation(user_id, podcast_id).await?; } Ok(ShareOutcome::Done(Box::new(ShareResponse { podcast: podcast_view(store, user_id, podcast_id).await?, share: share_view(store, user_id, podcast_id, discovery).await?, }))) } // --------------------------------------------------------------------------- // Podcasts found in the federation // --------------------------------------------------------------------------- /// A podcast from a public search hit: its id and the origin feed URL /// (`PodcastSearchHit::feed_url`). #[derive(Debug, Clone, Deserialize)] struct FoundPodcastRequest { podcast_id: String, feed_url: String, } /// The found podcast of a request. The id must hash from the URL, like a /// valid card's origin URL: a claimed moved URL or a URL of another podcast /// is refused (422), so the subscription gets the card's id. fn found_podcast(body: Value) -> ApiResult<(PodcastId, FeedUrl)> { let request: FoundPodcastRequest = decode(body)?; let podcast_id = parse_podcast_id(&request.podcast_id)?; let feed_url = FeedUrl::parse(&request.feed_url) .map_err(|error| ApiError::bad_request(format!("invalid feed URL: {error}")))?; if PodcastId::from_feed_url(&feed_url) != podcast_id { return Err(ApiError::new( 422, "the feed URL is not the URL this podcast id comes from", )); } Ok((podcast_id, feed_url)) } /// Seasons and episodes of a found podcast before subscribing: `{ /// "podcast_id", "feed_url" }` from the search hit. The feed is read /// through the SSRF-guarded fetcher and nothing is stored. pub(crate) async fn preview_found( store: &PodcastStore, fetcher: &FeedFetcher, user_id: i64, body: Value, ) -> ApiResult { let (podcast_id, feed_url) = found_podcast(body)?; let document = match fetcher.fetch(&feed_url, &Default::default()).await { Ok(FeedFetch::Fetched(document)) => document, Ok(FeedFetch::NotModified) => { return Err(ApiError::new( 502, "the feed could not be loaded: unexpected 304 Not Modified", )); } Err(error) => return Err(anyhow::Error::from(SubscribeUrlError::Fetch(error)).into()), }; let known = search::known_podcast(store, user_id, &podcast_id, &feed_url).await?; Ok(search::preview( &podcast_id, &feed_url, document.moved_permanently, &document.feed, known.as_ref(), )) } /// "Subscribe" on a found podcast: `{ "podcast_id", "feed_url" }` from the /// search hit. /// /// The subscription is the account's own and private, made like "add RSS" /// with the origin URL (fetch first, then `runner::subscribe_url`): its id /// is the card's id, or the account's existing podcast when the URL is a /// known feed URL or alias (progress and history continue). Redirects and /// `itunes:new-feed-url` of the feed itself become aliases as usual. When /// the account is already subscribed nothing is fetched or written. pub(crate) async fn subscribe_found( store: &PodcastStore, fetcher: &FeedFetcher, user_id: i64, body: Value, now_ms: i64, ) -> ApiResult { let (podcast_id, feed_url) = found_podcast(body)?; if let Some(known) = search::known_podcast(store, user_id, &podcast_id, &feed_url).await? && known.subscribed { return Ok(SubscribeResponse { podcast: podcast_view(store, user_id, &known.podcast_id).await?, already_subscribed: true, new_episodes: 0, }); } let subscription = runner::subscribe_url(store, fetcher, user_id, &feed_url, now_ms).await?; Ok(SubscribeResponse { podcast: podcast_view(store, user_id, &subscription.podcast_id).await?, already_subscribed: subscription.already_subscribed, new_episodes: subscription.refresh.new_episodes, }) } // --------------------------------------------------------------------------- // Episodes // --------------------------------------------------------------------------- /// Query string of the episode list. #[derive(Debug, Clone, Default, Deserialize)] pub(crate) struct EpisodeListParams { /// Season number, or `none` for the episodes without a season. #[serde(default)] pub(crate) season: Option, /// `unplayed`, `not_started`, `in_progress` or `played`. #[serde(default)] pub(crate) played: Option, /// Search text (titles and descriptions). #[serde(default)] pub(crate) q: Option, /// `newest` (default), `oldest`, `number` or `number_desc`. #[serde(default)] pub(crate) sort: Option, #[serde(default)] pub(crate) limit: Option, #[serde(default)] pub(crate) offset: Option, } impl EpisodeListParams { /// The store query (one row more than the page, to tell whether more /// rows follow). pub(crate) fn query(&self, podcast_id: PodcastId) -> ApiResult<(EpisodeQuery, usize)> { let blank = |value: &Option| { value .as_deref() .map(str::trim) .filter(|value| !value.is_empty()) .map(str::to_string) }; let season = match blank(&self.season).as_deref() { None | Some("all") => SeasonFilter::Any, Some("none") => SeasonFilter::NoSeason, Some(value) => SeasonFilter::Season( value .parse() .map_err(|_| ApiError::bad_request("invalid season"))?, ), }; let played = match blank(&self.played).as_deref() { None | Some("all") => PlayedFilter::Any, Some("unplayed") => PlayedFilter::Unplayed, Some("not_started") => PlayedFilter::NotStarted, Some("in_progress") => PlayedFilter::InProgress, Some("played") => PlayedFilter::Played, Some(_) => return Err(ApiError::bad_request("invalid played filter")), }; let sort = match blank(&self.sort).as_deref() { None | Some("newest") => EpisodeSort::NewestFirst, Some("oldest") => EpisodeSort::OldestFirst, Some("number") => EpisodeSort::EpisodeNumber, Some("number_desc") => EpisodeSort::EpisodeNumberDesc, Some(_) => return Err(ApiError::bad_request("invalid sort")), }; let limit = self .limit .unwrap_or(DEFAULT_EPISODE_PAGE) .clamp(1, MAX_EPISODE_PAGE); let mut query = EpisodeQuery::new(podcast_id); query.season = season; query.played = played; query.search = blank(&self.q); query.sort = sort; query.limit = Some(limit + 1); query.offset = self.offset.unwrap_or(0); Ok((query, limit)) } } #[derive(Debug, Serialize)] pub(crate) struct EpisodePage { pub(crate) episodes: Vec, pub(crate) offset: usize, pub(crate) has_more: bool, } /// A page of episodes of one podcast. pub(crate) async fn episodes( store: &PodcastStore, user_id: i64, podcast_id: &PodcastId, params: &EpisodeListParams, ) -> ApiResult { let podcast = store .podcast(user_id, podcast_id) .await? .ok_or_else(|| ApiError::not_found("unknown podcast"))?; let (query, limit) = params.query(podcast_id.clone())?; let mut rows = store.episodes(user_id, &query).await?; let has_more = rows.len() > limit; rows.truncate(limit); Ok(EpisodePage { episodes: rows .into_iter() .map(|item| EpisodeView::new(item, &podcast.meta)) .collect(), offset: query.offset, has_more, }) } /// Explicit progress actions of the episode list. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub(crate) enum EpisodeAction { /// "Start over": position 0, in progress. Restart, /// "Played": completed, no listening session, no invented time. MarkPlayed, /// "Unplayed": not started at 0. MarkUnplayed, } /// Runs an explicit progress action and returns the updated episode. pub(crate) async fn episode_action( store: &PodcastStore, user_id: i64, episode_id: &EpisodeId, action: EpisodeAction, ) -> ApiResult { let reference = catalog_ref(store, user_id, episode_id).await?; match action { EpisodeAction::Restart => { let session_id = format!("web-{}", uuid::Uuid::new_v4().simple()); store.restart(user_id, &reference, &session_id).await?; } EpisodeAction::MarkPlayed => { store.mark_played(user_id, &reference).await?; } EpisodeAction::MarkUnplayed => { store.mark_unplayed(user_id, &reference).await?; } } episode_view(store, user_id, episode_id).await } // --------------------------------------------------------------------------- // Playback // --------------------------------------------------------------------------- /// Body of `POST /episodes/{id}/playback`. #[derive(Debug, Clone, Default, Deserialize)] pub(crate) struct PlaybackRequest { /// The queue item's reference. Used only when the catalog does not know /// the episode yet (an item received through a handoff); it is recorded /// like a reference learned through sync. #[serde(default)] pub(crate) episode: Option, /// Start a listening session now (the browser is about to play). #[serde(default)] pub(crate) start: bool, /// Session id generated by the browser (required with `start`). #[serde(default)] pub(crate) session_id: Option, /// Position to start at: a handoff or the user's choice. Without it the /// episode resumes from its progress register. #[serde(default)] pub(crate) position_ms: Option, /// `PodcastEpisodeRef::progress_generation` of a handed-off queue item. #[serde(default)] pub(crate) carried_generation: Option, } /// How the browser plays an episode. #[derive(Debug, Clone, Serialize)] pub(crate) struct PlaybackResponse { pub(crate) episode_id: String, pub(crate) podcast_id: String, /// Session started by this request (`start`), with the generation its /// checkpoints use. pub(crate) session_id: Option, pub(crate) generation: Option, /// Where to start. pub(crate) position_ms: i64, /// Register status before this request. pub(crate) status: &'static str, pub(crate) duration_ms: Option, /// Publisher URL (default: the browser streams it directly). pub(crate) direct_url: String, /// Same-origin proxy path when the administrator enabled the proxy. pub(crate) proxy_url: Option, pub(crate) mime: Option, /// The progress register after this request: its generation and the /// session (or action) that wrote it. Before continuing a paused /// session the player checks that the register is still its own. pub(crate) register_generation: Option, pub(crate) register_session_id: Option, } /// Prepares an episode for the player and, with `start`, begins a session. pub(crate) async fn playback( store: &PodcastStore, user_id: i64, episode_id: &EpisodeId, body: Value, proxy_enabled: bool, ) -> ApiResult { let request: PlaybackRequest = decode(body)?; if store.episode_ref(user_id, episode_id).await?.is_none() { match request.episode.as_ref() { Some(reference) if reference.episode_id == *episode_id => { store.ensure_episode(user_id, reference).await?; } Some(_) => return Err(ApiError::bad_request("episode reference mismatch")), None => return Err(ApiError::not_found("unknown episode")), } } let reference = catalog_ref(store, user_id, episode_id).await?; let current = store.progress(user_id, episode_id).await?; let status = current .as_ref() .map_or(ProgressStatus::NotStarted, |record| record.status); let resume = current .as_ref() .map_or(0, ProgressRecord::resume_position_ms); let mut position_ms = request.position_ms.unwrap_or(resume).max(0); let (mut session_id, mut generation) = (None, None); let mut register = current; if request.start { let id = request .session_id .as_deref() .map(str::trim) .filter(|id| !id.is_empty()) .ok_or_else(|| ApiError::bad_request("session_id is required to start"))?; let write = store .start_session( user_id, &reference, id, position_ms, request.carried_generation, ) .await?; position_ms = write.record.position_ms; session_id = Some(write.session.session_id); generation = Some(write.session.generation); register = Some(write.record); } let (direct_url, mime) = store .audio_source(user_id, episode_id) .await? .ok_or_else(|| ApiError::not_found("unknown episode"))?; Ok(PlaybackResponse { episode_id: episode_id.to_string(), podcast_id: reference.podcast_id.to_string(), session_id, generation, position_ms, status: status_name(status), duration_ms: reference.duration_ms, direct_url, proxy_url: proxy_enabled.then(|| super::http::proxy_path(episode_id)), mime, register_generation: register.as_ref().map(|record| record.generation), register_session_id: register.map(|record| record.session_id), }) } /// What the player reports in `POST /episodes/{id}/progress`. #[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)] #[serde(rename_all = "snake_case")] pub(crate) enum ProgressEvent { /// Periodic save while playing (every 15–30 s). Checkpoint, /// The user paused. Pause, /// Playback stopped: another item, the page closed, the queue cleared. Stop, /// Playback moves to another device. Handoff, /// The user moved the position (explicit action). Seek, /// The audio reached the end of the stream. Ended, } impl ProgressEvent { /// Whether the event ends a stretch of listening that belongs in the /// session record. fn records_session(self) -> bool { matches!(self, Self::Pause | Self::Stop | Self::Handoff | Self::Ended) } } /// Body of `POST /episodes/{id}/progress`. #[derive(Debug, Clone, Deserialize)] pub(crate) struct ProgressRequest { pub(crate) session_id: String, /// Generation of the session's latest explicit action. pub(crate) generation: u64, pub(crate) event: ProgressEvent, pub(crate) position_ms: i64, /// Duration of the loaded audio, when the browser knows it. #[serde(default)] pub(crate) duration_ms: Option, /// Time actually listened in this session (seeks excluded). #[serde(default)] pub(crate) listened_ms: Option, /// When the session started (browser clock, unix ms). #[serde(default)] pub(crate) started_at_ms: Option, #[serde(default)] pub(crate) start_position_ms: Option, } /// Result of a progress report. #[derive(Debug, Clone, Serialize)] pub(crate) struct ProgressResponse { /// `written`, `superseded` (another device or action took over: stop /// writing at this generation) or `already_completed`. pub(crate) outcome: &'static str, /// Generation to use for the next checkpoints of this session. pub(crate) generation: u64, /// Register after the report. pub(crate) status: &'static str, pub(crate) position_ms: i64, /// Whether this report completed the episode. pub(crate) completed: bool, /// Whether the listening session was recorded (or grew). pub(crate) session_recorded: bool, } /// Stores a progress report of the player's current session. pub(crate) async fn progress( store: &PodcastStore, user_id: i64, episode_id: &EpisodeId, body: Value, now_ms: i64, ) -> ApiResult { let request: ProgressRequest = decode(body)?; let reference = catalog_ref(store, user_id, episode_id).await?; let position_ms = request.position_ms.max(0); let duration_ms = request .duration_ms .filter(|duration| *duration > 0) .or(reference.duration_ms); let session = ProgressSession { episode: reference.clone(), session_id: request.session_id.trim().to_string(), generation: request.generation, }; let reached_end = request.event == ProgressEvent::Ended || reaches_completion(position_ms, duration_ms); let outcome = match request.event { ProgressEvent::Seek => { CheckpointOutcome::Written(Box::new(store.seek(user_id, &session, position_ms).await?)) } _ if reached_end => { store .complete_if_current(user_id, &session, position_ms) .await? } _ => store.checkpoint(user_id, &session, position_ms).await?, }; let (name, record, completed) = match &outcome { CheckpointOutcome::Written(write) => ( "written", write.record.clone(), write.record.status == ProgressStatus::Completed && reached_end, ), CheckpointOutcome::Superseded { current } => ("superseded", current.clone(), false), CheckpointOutcome::AlreadyCompleted { current } => { ("already_completed", current.clone(), false) } }; let mut session_recorded = false; if request.event.records_session() && let Some(started_at_ms) = request.started_at_ms { let started_at_ms = started_at_ms.clamp(0, now_ms); let listened_ms = request .listened_ms .unwrap_or(0) .clamp(0, now_ms - started_at_ms); let listen = ListenSession { session_id: session.session_id.clone(), episode_id: episode_id.clone(), podcast_id: reference.podcast_id.clone(), device_id: devices::local_device_id(store.pool(), user_id).await?, started_at_ms, ended_at_ms: now_ms, start_position_ms: request.start_position_ms.unwrap_or(0).max(0), end_position_ms: position_ms, listened_ms, completed: reached_end, }; session_recorded = store .record_listen_session(user_id, &listen, Some(&reference)) .await? .is_some(); } Ok(ProgressResponse { outcome: name, generation: record.generation, status: status_name(record.status), position_ms: record.position_ms, completed, session_recorded, }) } #[cfg(test)] mod tests { use super::*; fn podcast() -> PodcastId { PodcastId::from_feed_url(&FeedUrl::parse("https://podcasts.example/feed.xml").unwrap()) } #[test] fn episode_list_params_map_to_store_queries() { let (query, limit) = EpisodeListParams::default().query(podcast()).unwrap(); assert_eq!(limit, DEFAULT_EPISODE_PAGE); assert_eq!(query.limit, Some(DEFAULT_EPISODE_PAGE + 1)); assert_eq!(query.season, SeasonFilter::Any); assert_eq!(query.played, PlayedFilter::Any); assert_eq!(query.sort, EpisodeSort::NewestFirst); assert_eq!(query.search, None); let params = EpisodeListParams { season: Some("3".into()), played: Some("in_progress".into()), q: Some(" interview ".into()), sort: Some("number_desc".into()), limit: Some(10_000), offset: Some(40), }; let (query, limit) = params.query(podcast()).unwrap(); assert_eq!(query.season, SeasonFilter::Season(3)); assert_eq!(query.played, PlayedFilter::InProgress); assert_eq!(query.search.as_deref(), Some("interview")); assert_eq!(query.sort, EpisodeSort::EpisodeNumberDesc); assert_eq!(limit, MAX_EPISODE_PAGE); assert_eq!(query.offset, 40); let none = EpisodeListParams { season: Some("none".into()), played: Some("played".into()), q: Some(" ".into()), sort: Some("oldest".into()), ..Default::default() }; let (query, _) = none.query(podcast()).unwrap(); assert_eq!(query.season, SeasonFilter::NoSeason); assert_eq!(query.played, PlayedFilter::Played); assert_eq!(query.search, None, "blank search is no filter"); assert_eq!(query.sort, EpisodeSort::OldestFirst); for bad in [ EpisodeListParams { season: Some("first".into()), ..Default::default() }, EpisodeListParams { played: Some("sometimes".into()), ..Default::default() }, EpisodeListParams { sort: Some("random".into()), ..Default::default() }, ] { assert_eq!(bad.query(podcast()).unwrap_err().status, 400); } } #[test] fn ids_and_bodies_are_validated_before_the_store() { assert_eq!(parse_podcast_id("nope").unwrap_err().status, 400); assert_eq!(parse_episode_id("pod1:abc").unwrap_err().status, 400); assert!(parse_podcast_id(podcast().as_str()).is_ok()); let error = decode::(serde_json::json!({ "session_id": "s", "generation": 1, "event": "rewind", "position_ms": 0 })) .unwrap_err(); assert_eq!(error.status, 400); let request: ProgressRequest = decode(serde_json::json!({ "session_id": "s", "generation": 3, "event": "handoff", "position_ms": 1200 })) .unwrap(); assert_eq!(request.event, ProgressEvent::Handoff); assert!(request.event.records_session()); assert!(!ProgressEvent::Checkpoint.records_session()); assert!(!ProgressEvent::Seek.records_session()); // A malformed episode reference in a playback request is a 400. let error = decode::(serde_json::json!({ "episode": { "episode_id": "not an id" } })) .unwrap_err(); assert_eq!(error.status, 400); let empty: PlaybackRequest = decode(serde_json::json!({})).unwrap(); assert!(!empty.start && empty.episode.is_none() && empty.position_ms.is_none()); } #[test] fn store_errors_map_to_http_statuses() { let unknown: ApiError = anyhow::Error::from(PodcastStoreError::UnknownPodcast(podcast())).into(); assert_eq!(unknown.status, 404); let not_subscribed: ApiError = anyhow::Error::from(PodcastStoreError::NotSubscribed(podcast())).into(); assert_eq!(not_subscribed.status, 409); let invalid: ApiError = super::super::invalid("bad").into(); assert_eq!(invalid.status, 400); let limit: ApiError = anyhow::Error::from(PodcastStoreError::SubscriptionLimit(1000)).into(); assert_eq!(limit.status, 422); assert_eq!(limit.message, "subscription limit reached (1000 podcasts)"); let references: ApiError = anyhow::Error::from(PodcastStoreError::ReferenceLimit(10_000)).into(); assert_eq!(references.status, 422); let refused: ApiError = anyhow::Error::from(SubscribeUrlError::Fetch(super::super::fetch::FetchError { kind: FetchErrorKind::Refused, message: "10.1.2.3 is a private address".into(), retry_after: None, })) .into(); assert_eq!(refused.status, 422); assert!( refused.message.contains("only public"), "{}", refused.message ); assert!( !refused.message.contains("10.1.2.3"), "no resolved addresses" ); let timeout: ApiError = anyhow::Error::from(SubscribeUrlError::Fetch(super::super::fetch::FetchError { kind: FetchErrorKind::Timeout, message: "timed out".into(), retry_after: None, })) .into(); assert_eq!(timeout.status, 502); let transport: ApiError = anyhow::Error::from(SubscribeUrlError::Fetch(super::super::fetch::FetchError { kind: FetchErrorKind::Transport, message: "error sending request: tcp connect error: Connection refused".into(), retry_after: None, })) .into(); assert_eq!(transport.status, 502); assert_eq!( transport.message, "the feed could not be loaded: could not connect to the server" ); let other: ApiError = anyhow::anyhow!("connection reset").into(); assert_eq!(other.status, 500); assert_eq!(other.message, "internal error", "internals are not shown"); } }