Files
furumi-web/src/podcasts/queries.rs
T
sanapachandClaude Opus 5.5 7f07cb206a Add a PostgreSQL podcast store with relay import
PodcastStore implements the music_dht::podcast contract per account:
catalog, feed aliases, episodes with a derived season view, the
subscription, share and progress registers, listening sessions and the
local-only fetch state. Received operations, snapshot records and local
actions share one apply path (materializers plus merge functions) under
a per-account advisory lock. Local actions append their operation to the
device-sync log with the next stamp of the web device and apply exactly
that operation in the same transaction.

Migration m_0056 creates the tables; m_0057 imports the registers that
0.13 kept in furumusic__fed_podcast_relay and the catalog rows of the
episode references in the operation log. The relay table is kept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:12:38 +02:00

665 lines
23 KiB
Rust

//! Read-only queries for the podcast UI and the player.
use anyhow::Result;
use music_dht::podcast::{
EpisodeId, EpisodeMeta, EpisodeType, FeedUrl, ListenSession, PodcastEpisodeRef, PodcastId,
PodcastMeta, ProgressRecord, ProgressStatus, ShareRecord, SubscriptionRecord, effective_share,
};
use sqlx::postgres::PgRow;
use sqlx::{PgConnection, Postgres, QueryBuilder, Row};
use super::apply;
use super::{
PodcastStore, SESSION_COLUMNS, episode_id_col, episode_search_norm, feed_url_col,
podcast_id_col, progress_columns, progress_from_row, session_from_row, u32_from_sql,
};
/// Which podcasts [`PodcastStore::list_podcasts`] returns.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub(crate) enum PodcastListFilter {
/// Podcasts with an active subscription.
#[default]
Subscribed,
/// Every podcast in the catalog, including unsubscribed ones and
/// podcasts only known from synced progress or queue items.
All,
}
/// A podcast with its personal state and episode counters.
#[derive(Debug, Clone, PartialEq)]
pub(crate) struct PodcastSummary {
/// Podcast id.
pub(crate) podcast_id: PodcastId,
/// Local channel metadata; `feed_url` is the URL this account fetches.
pub(crate) meta: PodcastMeta,
/// Whether the subscription register says subscribed.
pub(crate) subscribed: bool,
/// Whether the podcast must currently be published (`effective_share`).
pub(crate) shared: bool,
/// Episodes in the catalog.
pub(crate) episode_count: u64,
/// Episodes not completed (no progress, not started or in progress).
pub(crate) unplayed_count: u64,
/// Episodes in progress.
pub(crate) in_progress_count: u64,
/// Newest publication time.
pub(crate) latest_published_at_ms: Option<i64>,
/// Numbered seasons (episodes without a season are not counted).
pub(crate) season_count: u64,
}
/// One season group of a podcast. `season == None` groups the episodes
/// without `itunes:season`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct SeasonSummary {
/// Season number; `None` for episodes without a season.
pub(crate) season: Option<u32>,
/// Episodes in the group.
pub(crate) episode_count: u64,
/// Episodes not completed.
pub(crate) unplayed_count: u64,
/// Oldest publication time.
pub(crate) first_published_at_ms: Option<i64>,
/// Newest publication time.
pub(crate) last_published_at_ms: Option<i64>,
}
/// Season filter of an [`EpisodeQuery`].
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub(crate) enum SeasonFilter {
/// All episodes.
#[default]
Any,
/// Episodes of one season.
Season(u32),
/// Episodes without a season.
NoSeason,
}
/// Listening-state filter of an [`EpisodeQuery`].
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub(crate) enum PlayedFilter {
/// All episodes.
#[default]
Any,
/// Not completed (not started or in progress).
Unplayed,
/// Never started or marked unplayed.
NotStarted,
/// In progress.
InProgress,
/// Completed.
Played,
}
/// Episode ordering of an [`EpisodeQuery`].
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub(crate) enum EpisodeSort {
/// Newest publication first; undated episodes last.
#[default]
NewestFirst,
/// Oldest publication first; undated episodes last.
OldestFirst,
/// By season, then episode number, ascending; unnumbered last.
EpisodeNumber,
/// By season, then episode number, descending; unnumbered last.
EpisodeNumberDesc,
}
impl EpisodeSort {
fn order_by(self) -> &'static str {
match self {
Self::NewestFirst => "e.published_at_ms IS NULL, e.published_at_ms DESC, e.episode_id",
Self::OldestFirst => "e.published_at_ms IS NULL, e.published_at_ms, e.episode_id",
Self::EpisodeNumber => {
"e.season IS NULL, e.season, e.episode_number IS NULL, e.episode_number, \
e.published_at_ms IS NULL, e.published_at_ms, e.episode_id"
}
Self::EpisodeNumberDesc => {
"e.season IS NULL, e.season DESC, e.episode_number IS NULL, \
e.episode_number DESC, e.published_at_ms IS NULL, e.published_at_ms DESC, \
e.episode_id"
}
}
}
}
#[cfg(test)]
pub(crate) fn order_by_for_tests(sort: EpisodeSort) -> &'static str {
sort.order_by()
}
/// Parameters of [`PodcastStore::episodes`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct EpisodeQuery {
/// Podcast.
pub(crate) podcast_id: PodcastId,
/// Season filter.
pub(crate) season: SeasonFilter,
/// Listening-state filter.
pub(crate) played: PlayedFilter,
/// Text searched in titles and descriptions (`normalize_name`: Unicode
/// NFKC, case-insensitive substring match). Blank means no filter.
pub(crate) search: Option<String>,
/// Ordering.
pub(crate) sort: EpisodeSort,
/// Maximum rows (`None`: all).
pub(crate) limit: Option<usize>,
/// Rows to skip.
pub(crate) offset: usize,
}
impl EpisodeQuery {
/// All episodes of a podcast, newest first.
pub(crate) fn new(podcast_id: PodcastId) -> Self {
Self {
podcast_id,
season: SeasonFilter::Any,
played: PlayedFilter::Any,
search: None,
sort: EpisodeSort::NewestFirst,
limit: None,
offset: 0,
}
}
}
/// An episode with its personal state.
#[derive(Debug, Clone, PartialEq)]
pub(crate) struct EpisodeListItem {
/// Episode metadata (feed or synced reference).
pub(crate) episode: EpisodeMeta,
/// Progress register, if any.
pub(crate) progress: Option<ProgressRecord>,
/// Distinct completed listening sessions (`completed_listen_count`).
pub(crate) completed_count: u64,
/// Whether the latest refresh of the feed listed the episode.
pub(crate) in_feed: bool,
}
impl EpisodeListItem {
/// Listening status (`NotStarted` without a register).
pub(crate) fn status(&self) -> ProgressStatus {
self.progress
.as_ref()
.map_or(ProgressStatus::NotStarted, |progress| progress.status)
}
/// Position ordinary Play resumes from.
pub(crate) fn resume_position_ms(&self) -> i64 {
self.progress
.as_ref()
.map_or(0, ProgressRecord::resume_position_ms)
}
}
/// A listening session in history, with display titles when known.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct PodcastListenEntry {
/// The session.
pub(crate) session: ListenSession,
/// Episode title from the catalog.
pub(crate) episode_title: Option<String>,
/// Podcast title from the catalog.
pub(crate) podcast_title: Option<String>,
}
const EPISODE_COLUMNS: &str = "e.episode_id, e.podcast_id, e.guid, e.title, e.description, \
e.season, e.episode_number, e.episode_type, e.published_at_ms, e.duration_ms, \
e.audio_url, e.mime, e.byte_len, e.image_url, e.link";
const NOT_COMPLETED: &str = "COALESCE(g.status, 'not_started') <> 'completed'";
fn episode_from_row(row: &PgRow) -> sqlx::Result<EpisodeMeta> {
Ok(EpisodeMeta {
episode_id: episode_id_col(row, "episode_id")?,
podcast_id: podcast_id_col(row, "podcast_id")?,
guid: row.try_get("guid")?,
title: row.try_get("title")?,
description: row.try_get("description")?,
season: u32_from_sql(row.try_get("season")?),
episode_number: u32_from_sql(row.try_get("episode_number")?),
episode_type: EpisodeType::parse(&row.try_get::<String, _>("episode_type")?),
published_at_ms: row.try_get("published_at_ms")?,
duration_ms: row.try_get("duration_ms")?,
audio_url: row.try_get("audio_url")?,
mime: row.try_get("mime")?,
byte_len: row
.try_get::<Option<i64>, _>("byte_len")?
.and_then(|len| u64::try_from(len).ok()),
image_url: row.try_get("image_url")?,
link: row.try_get("link")?,
})
}
fn list_item_from_row(row: &PgRow) -> sqlx::Result<EpisodeListItem> {
let progress = if row.try_get::<Option<String>, _>("g_episode_id")?.is_some() {
Some(progress_from_row(row, "g_")?)
} else {
None
};
Ok(EpisodeListItem {
episode: episode_from_row(row)?,
in_feed: row.try_get("in_feed")?,
progress,
completed_count: count(row.try_get("completed_count")?),
})
}
fn count(value: i64) -> u64 {
u64::try_from(value).unwrap_or(0)
}
pub(crate) async fn episode_meta_in(
conn: &mut PgConnection,
user_id: i64,
episode_id: &EpisodeId,
) -> Result<Option<EpisodeMeta>> {
let row = sqlx::query(&format!(
"SELECT {EPISODE_COLUMNS} FROM furumusic__podcast_episode e
WHERE e.user_id = $1 AND e.episode_id = $2"
))
.bind(user_id)
.bind(episode_id.as_str())
.fetch_optional(&mut *conn)
.await?;
Ok(row.as_ref().map(episode_from_row).transpose()?)
}
pub(crate) async fn podcast_meta_in(
conn: &mut PgConnection,
user_id: i64,
podcast_id: &PodcastId,
) -> Result<Option<PodcastMeta>> {
let row = sqlx::query(
"SELECT feed_url, title, author, description, link, image_url
FROM furumusic__podcast WHERE user_id = $1 AND podcast_id = $2",
)
.bind(user_id)
.bind(podcast_id.as_str())
.fetch_optional(&mut *conn)
.await?;
let Some(row) = row else {
return Ok(None);
};
Ok(Some(PodcastMeta {
feed_url: feed_url_col(&row, "feed_url")?,
title: row.try_get("title")?,
author: row.try_get("author")?,
description: row.try_get("description")?,
link: row.try_get("link")?,
image_url: row.try_get("image_url")?,
}))
}
/// Queue reference of a catalog episode, with `progress_generation` set to
/// the generation of its progress register (handoff hint).
pub(crate) async fn episode_ref_in(
conn: &mut PgConnection,
user_id: i64,
episode_id: &EpisodeId,
) -> Result<Option<PodcastEpisodeRef>> {
let Some(episode) = episode_meta_in(conn, user_id, episode_id).await? else {
return Ok(None);
};
let Some(podcast) = podcast_meta_in(conn, user_id, &episode.podcast_id).await? else {
return Ok(None);
};
let mut reference = episode.to_ref(&podcast);
reference.progress_generation = apply::load_progress(conn, user_id, episode_id)
.await?
.map(|progress| progress.generation);
Ok(Some(reference))
}
async fn summary_in(
conn: &mut PgConnection,
user_id: i64,
podcast_id: &PodcastId,
) -> Result<Option<PodcastSummary>> {
let Some(meta) = podcast_meta_in(conn, user_id, podcast_id).await? else {
return Ok(None);
};
let row = sqlx::query(&format!(
"SELECT COUNT(*) AS episode_count,
COUNT(*) FILTER (WHERE {NOT_COMPLETED}) AS unplayed_count,
COUNT(*) FILTER (WHERE g.status = 'in_progress') AS in_progress_count,
MAX(e.published_at_ms) AS latest,
(SELECT COUNT(DISTINCT e2.season) FROM furumusic__podcast_episode e2
WHERE e2.user_id = $1 AND e2.podcast_id = $2) AS season_count
FROM furumusic__podcast_episode e
LEFT JOIN furumusic__podcast_progress g
ON g.user_id = e.user_id AND g.episode_id = e.episode_id
WHERE e.user_id = $1 AND e.podcast_id = $2"
))
.bind(user_id)
.bind(podcast_id.as_str())
.fetch_one(&mut *conn)
.await?;
let subscription = apply::load_subscription_register(conn, user_id, podcast_id).await?;
let share = apply::load_share(conn, user_id, podcast_id).await?;
Ok(Some(PodcastSummary {
podcast_id: podcast_id.clone(),
meta,
subscribed: subscription
.as_ref()
.is_some_and(|record| record.subscribed),
shared: effective_share(subscription.as_ref(), share.as_ref()),
episode_count: count(row.try_get("episode_count")?),
unplayed_count: count(row.try_get("unplayed_count")?),
in_progress_count: count(row.try_get("in_progress_count")?),
latest_published_at_ms: row.try_get("latest")?,
season_count: count(row.try_get("season_count")?),
}))
}
/// Computes the cached search text of episodes that do not have it yet
/// (rows imported by the `m_0057` migration).
async fn backfill_search_norm(
conn: &mut PgConnection,
user_id: i64,
podcast_id: &PodcastId,
) -> Result<()> {
let rows = sqlx::query(
"SELECT episode_id, title, description FROM furumusic__podcast_episode
WHERE user_id = $1 AND podcast_id = $2 AND search_norm IS NULL",
)
.bind(user_id)
.bind(podcast_id.as_str())
.fetch_all(&mut *conn)
.await?;
for row in rows {
let title: String = row.try_get("title")?;
let description: Option<String> = row.try_get("description")?;
sqlx::query(
"UPDATE furumusic__podcast_episode SET search_norm = $3
WHERE user_id = $1 AND episode_id = $2 AND search_norm IS NULL",
)
.bind(user_id)
.bind(row.try_get::<String, _>("episode_id")?)
.bind(episode_search_norm(&title, description.as_deref()))
.execute(&mut *conn)
.await?;
}
Ok(())
}
impl PodcastStore {
/// Podcasts with subscription state and counters, sorted by title.
pub(crate) async fn list_podcasts(
&self,
user_id: i64,
filter: PodcastListFilter,
) -> Result<Vec<PodcastSummary>> {
let mut conn = self.pool.acquire().await?;
let join = match filter {
PodcastListFilter::Subscribed => {
"JOIN furumusic__podcast_subscription r
ON r.user_id = p.user_id AND r.podcast_id = p.podcast_id AND r.subscribed"
}
PodcastListFilter::All => "",
};
let rows = sqlx::query(&format!(
"SELECT p.podcast_id FROM furumusic__podcast p {join}
WHERE p.user_id = $1
ORDER BY lower(p.title), p.podcast_id"
))
.bind(user_id)
.fetch_all(&mut *conn)
.await?;
let ids = rows
.iter()
.map(|row| podcast_id_col(row, "podcast_id"))
.collect::<sqlx::Result<Vec<_>>>()?;
let mut out = Vec::with_capacity(ids.len());
for id in ids {
if let Some(summary) = summary_in(&mut conn, user_id, &id).await? {
out.push(summary);
}
}
Ok(out)
}
/// One podcast with subscription state and counters.
pub(crate) async fn podcast(
&self,
user_id: i64,
podcast_id: &PodcastId,
) -> Result<Option<PodcastSummary>> {
let mut conn = self.pool.acquire().await?;
summary_in(&mut conn, user_id, podcast_id).await
}
/// The subscription register (with the stored alias set), if any.
pub(crate) async fn subscription(
&self,
user_id: i64,
podcast_id: &PodcastId,
) -> Result<Option<SubscriptionRecord>> {
let mut conn = self.pool.acquire().await?;
apply::load_subscription_register(&mut conn, user_id, podcast_id).await
}
/// The share register, if any.
pub(crate) async fn share(
&self,
user_id: i64,
podcast_id: &PodcastId,
) -> Result<Option<ShareRecord>> {
let mut conn = self.pool.acquire().await?;
apply::load_share(&mut conn, user_id, podcast_id).await
}
/// The bounded, synced feed alias set of a podcast.
pub(crate) async fn feed_aliases(
&self,
user_id: i64,
podcast_id: &PodcastId,
) -> Result<Vec<FeedUrl>> {
let mut conn = self.pool.acquire().await?;
apply::load_aliases(&mut conn, user_id, podcast_id).await
}
/// Season groups of a podcast: numbered seasons ascending, then the
/// group of episodes without a season.
pub(crate) async fn seasons(
&self,
user_id: i64,
podcast_id: &PodcastId,
) -> Result<Vec<SeasonSummary>> {
let rows = sqlx::query(&format!(
"SELECT s.season, s.episode_count, s.first_published_at_ms, s.last_published_at_ms,
(SELECT COUNT(*) FROM furumusic__podcast_episode e
LEFT JOIN furumusic__podcast_progress g
ON g.user_id = e.user_id AND g.episode_id = e.episode_id
WHERE e.user_id = s.user_id AND e.podcast_id = s.podcast_id
AND e.season IS NOT DISTINCT FROM s.season
AND {NOT_COMPLETED}) AS unplayed_count
FROM furumusic__podcast_season s
WHERE s.user_id = $1 AND s.podcast_id = $2
ORDER BY s.season IS NULL, s.season"
))
.bind(user_id)
.bind(podcast_id.as_str())
.fetch_all(&self.pool)
.await?;
let seasons = rows
.iter()
.map(|row| {
Ok(SeasonSummary {
season: u32_from_sql(row.try_get("season")?),
episode_count: count(row.try_get("episode_count")?),
first_published_at_ms: row.try_get("first_published_at_ms")?,
last_published_at_ms: row.try_get("last_published_at_ms")?,
unplayed_count: count(row.try_get("unplayed_count")?),
})
})
.collect::<sqlx::Result<Vec<_>>>()?;
Ok(seasons)
}
/// Episodes of a podcast or season with their progress.
pub(crate) async fn episodes(
&self,
user_id: i64,
query: &EpisodeQuery,
) -> Result<Vec<EpisodeListItem>> {
let mut conn = self.pool.acquire().await?;
let needle = query
.search
.as_deref()
.map(music_dht::normalize_name)
.filter(|needle| !needle.is_empty());
if needle.is_some() {
backfill_search_norm(&mut conn, user_id, &query.podcast_id).await?;
}
let mut sql: QueryBuilder<'_, Postgres> = QueryBuilder::new(format!(
"SELECT {EPISODE_COLUMNS}, e.in_feed, {},
(SELECT COUNT(*) FROM furumusic__podcast_listen_session s
WHERE s.user_id = e.user_id AND s.episode_id = e.episode_id
AND s.completed) AS completed_count
FROM furumusic__podcast_episode e
LEFT JOIN furumusic__podcast_progress g
ON g.user_id = e.user_id AND g.episode_id = e.episode_id
WHERE e.user_id = ",
progress_columns("g", "g_")
));
sql.push_bind(user_id);
sql.push(" AND e.podcast_id = ");
sql.push_bind(query.podcast_id.as_str().to_string());
match query.season {
SeasonFilter::Any => {}
SeasonFilter::Season(season) => {
sql.push(" AND e.season = ");
sql.push_bind(i64::from(season));
}
SeasonFilter::NoSeason => {
sql.push(" AND e.season IS NULL");
}
}
match query.played {
PlayedFilter::Any => {}
PlayedFilter::Unplayed => {
sql.push(format!(" AND {NOT_COMPLETED}"));
}
PlayedFilter::NotStarted => {
sql.push(" AND COALESCE(g.status, 'not_started') = 'not_started'");
}
PlayedFilter::InProgress => {
sql.push(" AND g.status = 'in_progress'");
}
PlayedFilter::Played => {
sql.push(" AND g.status = 'completed'");
}
}
if let Some(needle) = needle {
sql.push(" AND strpos(e.search_norm, ");
sql.push_bind(needle);
sql.push(") > 0");
}
sql.push(format!(" ORDER BY {}", query.sort.order_by()));
if let Some(limit) = query.limit {
sql.push(" LIMIT ");
sql.push_bind(i64::try_from(limit).unwrap_or(i64::MAX));
}
sql.push(" OFFSET ");
sql.push_bind(i64::try_from(query.offset).unwrap_or(i64::MAX));
let rows = sql.build().fetch_all(&mut *conn).await?;
Ok(rows
.iter()
.map(list_item_from_row)
.collect::<sqlx::Result<Vec<_>>>()?)
}
/// One episode with its progress.
pub(crate) async fn episode(
&self,
user_id: i64,
episode_id: &EpisodeId,
) -> Result<Option<EpisodeListItem>> {
let row = sqlx::query(&format!(
"SELECT {EPISODE_COLUMNS}, e.in_feed, {},
(SELECT COUNT(*) FROM furumusic__podcast_listen_session s
WHERE s.user_id = e.user_id AND s.episode_id = e.episode_id
AND s.completed) AS completed_count
FROM furumusic__podcast_episode e
LEFT JOIN furumusic__podcast_progress g
ON g.user_id = e.user_id AND g.episode_id = e.episode_id
WHERE e.user_id = $1 AND e.episode_id = $2",
progress_columns("g", "g_")
))
.bind(user_id)
.bind(episode_id.as_str())
.fetch_optional(&self.pool)
.await?;
Ok(row.as_ref().map(list_item_from_row).transpose()?)
}
/// Position ordinary Play resumes from
/// (`ProgressRecord::resume_position_ms`, 0 without progress).
pub(crate) async fn resume_position_ms(
&self,
user_id: i64,
episode_id: &EpisodeId,
) -> Result<i64> {
Ok(self
.progress(user_id, episode_id)
.await?
.map_or(0, |progress| progress.resume_position_ms()))
}
/// Listening history (sessions that `should_record`), newest first.
pub(crate) async fn listen_history(
&self,
user_id: i64,
podcast_id: Option<&PodcastId>,
limit: usize,
) -> Result<Vec<PodcastListenEntry>> {
let rows = sqlx::query(&format!(
"SELECT {SESSION_COLUMNS}, e.title AS episode_title, p.title AS podcast_title
FROM furumusic__podcast_listen_session s
LEFT JOIN furumusic__podcast_episode e
ON e.user_id = s.user_id AND e.episode_id = s.episode_id
LEFT JOIN furumusic__podcast p
ON p.user_id = s.user_id AND p.podcast_id = s.podcast_id
WHERE s.user_id = $1 AND (s.completed OR s.listened_ms >= $2)
AND ($3::text IS NULL OR s.podcast_id = $3)
ORDER BY s.ended_at_ms DESC, s.session_id DESC
LIMIT $4"
))
.bind(user_id)
.bind(music_dht::podcast::MIN_RECORDED_EPISODE_LISTEN_MS)
.bind(podcast_id.map(PodcastId::as_str))
.bind(i64::try_from(limit).unwrap_or(i64::MAX))
.fetch_all(&self.pool)
.await?;
Ok(rows
.iter()
.map(|row| {
Ok(PodcastListenEntry {
session: session_from_row(row)?,
episode_title: row.try_get("episode_title")?,
podcast_title: row.try_get("podcast_title")?,
})
})
.collect::<sqlx::Result<Vec<_>>>()?)
}
/// Number of distinct completed sessions of an episode.
pub(crate) async fn completed_listen_count(
&self,
user_id: i64,
episode_id: &EpisodeId,
) -> Result<u64> {
let total: i64 = sqlx::query_scalar(
"SELECT COUNT(*) FROM furumusic__podcast_listen_session
WHERE user_id = $1 AND episode_id = $2 AND completed",
)
.bind(user_id)
.bind(episode_id.as_str())
.fetch_one(&self.pool)
.await?;
Ok(count(total))
}
}