Files
furumi-web/src/podcasts/api.rs
T

1359 lines
50 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! 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;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use super::discovery::Discovery;
use super::fetch::{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<String>) -> Self {
Self {
status,
message: message.into(),
}
}
fn bad_request(message: impl Into<String>) -> Self {
Self::new(400, message)
}
fn not_found(message: impl Into<String>) -> Self {
Self::new(404, message)
}
}
impl From<anyhow::Error> for ApiError {
fn from(error: anyhow::Error) -> Self {
if let Some(error) = error.downcast_ref::<PodcastStoreError>() {
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::<SubscribeUrlError>() {
// 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<T> = Result<T, ApiError>;
pub(crate) fn parse_podcast_id(value: &str) -> ApiResult<PodcastId> {
PodcastId::parse(value).map_err(|_| ApiError::bad_request("invalid podcast id"))
}
pub(crate) fn parse_episode_id(value: &str) -> ApiResult<EpisodeId> {
EpisodeId::parse(value).map_err(|_| ApiError::bad_request("invalid episode id"))
}
fn decode<T: serde::de::DeserializeOwned>(body: Value) -> ApiResult<T> {
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<i64>,
pub(crate) last_success_at_ms: Option<i64>,
pub(crate) next_check_at_ms: Option<i64>,
pub(crate) last_error: Option<String>,
pub(crate) consecutive_failures: u32,
}
impl From<FetchState> 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<String>,
pub(crate) description: Option<String>,
pub(crate) link: Option<String>,
pub(crate) image_url: Option<String>,
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<i64>,
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<u32>,
pub(crate) episode_count: u64,
pub(crate) unplayed_count: u64,
pub(crate) first_published_at_ms: Option<i64>,
pub(crate) last_published_at_ms: Option<i64>,
}
impl From<SeasonSummary> 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<String>,
pub(crate) season: Option<u32>,
pub(crate) episode_number: Option<u32>,
pub(crate) episode_type: &'static str,
pub(crate) published_at_ms: Option<i64>,
pub(crate) duration_ms: Option<i64>,
pub(crate) image_url: Option<String>,
pub(crate) link: Option<String>,
/// 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<PodcastView> {
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<EpisodeView> {
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<PodcastEpisodeRef> {
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<PodcastView>,
}
/// 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<PodcastList> {
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<String>,
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<SeasonView>,
/// Newest listening sessions of this podcast, from every device.
pub(crate) history: Vec<HistoryView>,
}
/// One podcast with its season groups and its public discovery state
/// (`discovery`: whether the server's overlay runs).
pub(crate) async fn podcast_detail(
store: &PodcastStore,
user_id: i64,
podcast_id: &PodcastId,
discovery: Discovery<'_>,
) -> ApiResult<PodcastDetail> {
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<SubscribeResponse> {
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<PodcastView> {
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<PodcastView> {
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<String>,
/// Why the card's feed URLs may be private (`PodcastCardSpec::
/// privacy_warnings`); enabling sharing must be confirmed when present.
pub(crate) warnings: Vec<FeedUrlPrivacyWarning>,
/// Feed URL the card would publish.
pub(crate) feed_url: Option<String>,
/// Origin URL the podcast id comes from, when the feed moved.
pub(crate) id_feed_url: Option<String>,
/// `running` when the server's node runs public discovery,
/// `unavailable` when the node runs but the overlay failed to start,
/// `off` when federation is not running.
pub(crate) discovery: &'static str,
/// This server's node currently publishes a card of this podcast and
/// this account shares it. Only this server's own publication: another
/// player of the account (a TUI) publishes its own card from its own
/// node, which this flag does not show.
pub(crate) published: bool,
/// Why the server does not publish a shared, publishable podcast after
/// its last round: `over_limit` (beyond this account's part of the
/// server's publication budget) or `failed` (the card could not be
/// signed or stored). `null` otherwise.
pub(crate) held: Option<&'static str>,
}
/// The account's [`ShareView`] of a podcast.
pub(crate) async fn share_view(
store: &PodcastStore,
user_id: i64,
podcast_id: &PodcastId,
discovery: Discovery<'_>,
) -> ApiResult<ShareView> {
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: discovery.state(),
published: false,
held: None,
};
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.dht()
&& account.publishable()
{
// The overlay's cache is not essential to the podcast page: when it
// cannot be read, the card shows as not published yet.
view.published = match dht.published().await {
Ok(publications) => publications
.iter()
.any(|publication| publication.active && publication.podcast_id == *podcast_id),
Err(error) => {
tracing::warn!("podcast publications unavailable: {error}");
false
}
};
if !view.published {
view.held = super::discovery::held_reason(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<String>,
}
#[derive(Debug, Clone, Deserialize)]
struct ShareRequest {
shared: bool,
/// Confirmation of the card's URLs despite its privacy warnings.
#[serde(default)]
confirm: Option<ShareConfirmRequest>,
}
#[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<ShareResponse>),
/// 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: Discovery<'_>,
now_ms: i64,
) -> ApiResult<ShareOutcome> {
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. `subscribed`
/// also holds when the account follows the feed under the address it
/// moved to (a permanent redirect or the feed's `itunes:new-feed-url`).
pub(crate) async fn preview_found(
store: &PodcastStore,
fetcher: &FeedFetcher,
user_id: i64,
body: Value,
) -> ApiResult<search::PodcastPreview> {
let (podcast_id, feed_url) = found_podcast(body)?;
let document = runner::fetch_to_subscribe(fetcher, &feed_url).await?;
let urls = runner::document_urls(&feed_url, &document);
let known = search::known_podcast(store, user_id, &podcast_id, &urls).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_fetched`): its
/// id is the card's id, or the account's existing podcast when the URL, or
/// the address the feed moved to, 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
/// (by id or a known URL, before or after the fetch) nothing is written.
pub(crate) async fn subscribe_found(
store: &PodcastStore,
fetcher: &FeedFetcher,
user_id: i64,
body: Value,
now_ms: i64,
) -> ApiResult<SubscribeResponse> {
let (podcast_id, feed_url) = found_podcast(body)?;
let already = async |known: PodcastSummary| -> ApiResult<SubscribeResponse> {
Ok(SubscribeResponse {
podcast: podcast_view(store, user_id, &known.podcast_id).await?,
already_subscribed: true,
new_episodes: 0,
})
};
if let Some(known) =
search::known_podcast(store, user_id, &podcast_id, std::slice::from_ref(&feed_url)).await?
&& known.subscribed
{
return already(known).await;
}
let document = runner::fetch_to_subscribe(fetcher, &feed_url).await?;
let urls = runner::document_urls(&feed_url, &document);
if let Some(known) = search::known_podcast(store, user_id, &podcast_id, &urls).await?
&& known.subscribed
{
return already(known).await;
}
let subscription =
runner::subscribe_fetched(store, user_id, &feed_url, &document, 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<String>,
/// `unplayed`, `not_started`, `in_progress` or `played`.
#[serde(default)]
pub(crate) played: Option<String>,
/// Search text (titles and descriptions).
#[serde(default)]
pub(crate) q: Option<String>,
/// `newest` (default), `oldest`, `number` or `number_desc`.
#[serde(default)]
pub(crate) sort: Option<String>,
#[serde(default)]
pub(crate) limit: Option<usize>,
#[serde(default)]
pub(crate) offset: Option<usize>,
}
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<String>| {
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<EpisodeView>,
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<EpisodePage> {
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<EpisodeView> {
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<PodcastEpisodeRef>,
/// 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<String>,
/// 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<i64>,
/// `PodcastEpisodeRef::progress_generation` of a handed-off queue item.
#[serde(default)]
pub(crate) carried_generation: Option<u64>,
}
/// 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<String>,
pub(crate) generation: Option<u64>,
/// Where to start.
pub(crate) position_ms: i64,
/// Register status before this request.
pub(crate) status: &'static str,
pub(crate) duration_ms: Option<i64>,
/// 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<String>,
pub(crate) mime: Option<String>,
/// 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<u64>,
pub(crate) register_session_id: Option<String>,
}
/// 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<PlaybackResponse> {
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<i64>,
/// Time actually listened in this session (seeks excluded).
#[serde(default)]
pub(crate) listened_ms: Option<i64>,
/// When the session started (browser clock, unix ms).
#[serde(default)]
pub(crate) started_at_ms: Option<i64>,
#[serde(default)]
pub(crate) start_position_ms: Option<i64>,
}
/// 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<ProgressResponse> {
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::<ProgressRequest>(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::<PlaybackRequest>(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");
}
}