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

782 lines
27 KiB
Rust

//! HTTP endpoints of the podcast runtime, mounted at `/api/podcasts`. The
//! request handling lives in [`super::api`]; this module authenticates (the
//! session or a bearer token of the signed-in account) and maps results to
//! JSON responses.
//!
//! Podcast UI:
//!
//! * `GET /feeds[?all=1]` — subscribed podcasts (with `all`, also
//! unsubscribed ones and podcasts only known from synced progress), with
//! counters and the local fetch state.
//! * `POST /feeds` `{url}` — "add RSS": fetch, then subscribe (private).
//! * `GET /feeds/{podcast_id}` — one podcast and its season groups.
//! * `GET /feeds/{podcast_id}/episodes?season=&played=&q=&sort=&limit=&offset=`
//! * `POST /feeds/{podcast_id}/subscribe`, `POST /feeds/{podcast_id}/unsubscribe`
//! (unsubscribing keeps progress and history).
//! * `POST /episodes/{episode_id}/restart|played|unplayed` — explicit
//! progress actions.
//! * `POST /{podcast_id}/refresh` — manual feed refresh of a subscribed
//! podcast (ignores the failure backoff, at most every 30 s).
//!
//! Web player:
//!
//! * `POST /episodes/{episode_id}/playback` — audio source, resume position
//! and (when playing starts) a new listening session.
//! * `POST /episodes/{episode_id}/progress` — checkpoints, pause, seek,
//! stop, handoff and end of stream of that session (also sent with
//! `navigator.sendBeacon` when the page is hidden).
//! * `GET /episodes/{episode_id}/source` — how the browser gets the audio:
//! the publisher URL (default, the browser streams it directly) and the
//! proxy URL when the administrator enabled the proxy.
//! * `GET /episodes/{episode_id}/audio` — the optional audio proxy
//! (`podcast_audio_proxy_enabled`). It takes an episode id, never a URL,
//! and only serves episodes of the signed-in account.
use std::sync::Arc;
use cot::db::Database;
use cot::http::StatusCode;
use cot::http::header::{
ACCEPT_RANGES, CACHE_CONTROL, CONTENT_LENGTH, CONTENT_RANGE, CONTENT_TYPE, RANGE, RETRY_AFTER,
};
use cot::json::Json;
use cot::request::extractors::{Path, UrlQuery};
use cot::response::IntoResponse;
use cot::router::method::{get, post};
use cot::router::{Route, Router};
use cot::session::Session;
use cot::{App, Body};
use futures_util::TryStreamExt;
use music_dht::podcast::{EpisodeId, PodcastId};
use serde::{Deserialize, Serialize};
use super::api::{self, ApiError, EpisodeAction, EpisodeListParams};
use super::fetch::FeedFetcher;
use super::proxy::AudioProxy;
use super::runner::{self, ManualRefreshError, TargetResult};
use super::{PodcastStore, now_ms};
use crate::auth;
use crate::config::AppConfig;
fn json_error(status: StatusCode, message: &str) -> cot::response::Response {
let body = serde_json::json!({ "error": message });
cot::http::Response::builder()
.status(status)
.header(CONTENT_TYPE, "application/json")
.header(CACHE_CONTROL, "private, no-store")
.body(Body::fixed(body.to_string()))
.expect("valid response")
}
fn internal(error: impl std::fmt::Display) -> cot::Error {
cot::Error::internal(error.to_string())
}
fn api_error(error: ApiError) -> cot::response::Response {
json_error(
StatusCode::from_u16(error.status).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR),
&error.message,
)
}
/// JSON response of an [`api`] result; personal data is never cached.
fn api_response<T: Serialize>(result: api::ApiResult<T>) -> cot::Result<cot::response::Response> {
match result {
Ok(value) => {
let mut response = Json(value).into_response()?;
response
.headers_mut()
.insert(CACHE_CONTROL, "private, no-store".parse().expect("static"));
Ok(response)
}
Err(error) => Ok(api_error(error)),
}
}
/// The signed-in account (session or bearer token).
async fn signed_in(auth_ctx: &auth::AuthContext, session: &Session, db: &Database) -> Option<i64> {
auth::get_request_user(auth_ctx, session, db)
.await
.map(|user| user.id)
}
fn unauthorized() -> cot::response::Response {
json_error(StatusCode::UNAUTHORIZED, "not authenticated")
}
/// Largest JSON body accepted (a playback request carries one episode reference).
const MAX_JSON_BODY: usize = 64 * 1024;
/// Whether a `Content-Type` value is `application/json` (parameters such
/// as `charset` allowed).
fn is_json_content_type(value: Option<&str>) -> bool {
value
.and_then(|value| value.split(';').next())
.is_some_and(|essence| essence.trim().eq_ignore_ascii_case("application/json"))
}
/// Request body as JSON (`{}` when empty); malformed JSON is a 400.
///
/// A body must be sent as `application/json` (415 otherwise), like cot's
/// `Json` extractor requires on the other player endpoints: a cross-origin
/// page can only send that type after a CORS preflight, while `text/plain`
/// and form bodies need none and would carry the session cookie from a
/// same-site page. `navigator.sendBeacon` sends a Blob typed
/// `application/json`.
async fn json_body(request: cot::request::Request) -> Result<serde_json::Value, ApiError> {
let json = is_json_content_type(
request
.headers()
.get(CONTENT_TYPE)
.and_then(|value| value.to_str().ok()),
);
let bytes = request
.into_body()
.into_bytes_limited(MAX_JSON_BODY)
.await
.map_err(|error| ApiError::new(400, format!("unreadable body: {error}")))?;
if bytes.iter().all(u8::is_ascii_whitespace) {
return Ok(serde_json::Value::Object(Default::default()));
}
if !json {
return Err(ApiError::new(415, "the body must be application/json"));
}
serde_json::from_slice(&bytes).map_err(|error| ApiError::new(400, error.to_string()))
}
/// Shared state of the handlers.
#[derive(Clone)]
struct State {
config: Arc<AppConfig>,
pool: Arc<tokio::sync::OnceCell<sqlx::PgPool>>,
fetcher: Arc<tokio::sync::OnceCell<FeedFetcher>>,
proxy: Arc<tokio::sync::OnceCell<AudioProxy>>,
}
impl State {
async fn store(&self) -> cot::Result<PodcastStore> {
let pool = self
.pool
.get_or_try_init(|| async {
sqlx::postgres::PgPoolOptions::new()
.max_connections(5)
.connect(&self.config.database_url)
.await
})
.await
.map_err(internal)?;
Ok(PodcastStore::new(pool.clone()))
}
async fn fetcher(&self) -> cot::Result<&FeedFetcher> {
self.fetcher
.get_or_try_init(|| async { FeedFetcher::new() })
.await
.map_err(internal)
}
async fn proxy(&self) -> cot::Result<&AudioProxy> {
self.proxy
.get_or_try_init(|| async { AudioProxy::new() })
.await
.map_err(internal)
}
}
/// The podcast runtime endpoints (see the module documentation).
pub(crate) struct PodcastsApp {
state: State,
}
impl PodcastsApp {
pub(crate) fn new(config: Arc<AppConfig>) -> Self {
Self {
state: State {
config,
pool: Arc::new(tokio::sync::OnceCell::new()),
fetcher: Arc::new(tokio::sync::OnceCell::new()),
proxy: Arc::new(tokio::sync::OnceCell::new()),
},
}
}
}
#[derive(Debug, Deserialize)]
struct PodcastPath {
podcast_id: String,
}
#[derive(Debug, Deserialize)]
struct EpisodePath {
episode_id: String,
}
/// Path of the proxy endpoint for an episode.
pub(crate) fn proxy_path(episode_id: &EpisodeId) -> String {
format!("/api/podcasts/episodes/{episode_id}/audio")
}
#[derive(Debug, Serialize)]
struct RefreshResponse {
status: &'static str,
new_episodes: usize,
updated_episodes: usize,
unchanged_episodes: usize,
skipped_items: usize,
feed_url: Option<String>,
error: Option<String>,
next_check_at_ms: Option<i64>,
}
impl RefreshResponse {
fn from_result(result: TargetResult) -> Self {
let mut response = Self {
status: "",
new_episodes: 0,
updated_episodes: 0,
unchanged_episodes: 0,
skipped_items: 0,
feed_url: None,
error: None,
next_check_at_ms: None,
};
match result {
TargetResult::Updated(outcome) => {
response.status = "updated";
response.new_episodes = outcome.new_episodes;
response.updated_episodes = outcome.updated_episodes;
response.unchanged_episodes = outcome.unchanged_episodes;
response.skipped_items = outcome.skipped_items;
response.feed_url = outcome.feed_url.map(String::from);
}
TargetResult::NotModified => response.status = "not_modified",
TargetResult::Failed {
error,
next_check_at_ms,
..
} => {
response.status = "failed";
response.error = Some(error);
response.next_check_at_ms = Some(next_check_at_ms);
}
TargetResult::Skipped(reason) => {
response.status = "skipped";
response.error = Some(reason);
}
}
response
}
}
async fn refresh_handler(
state: State,
auth_ctx: auth::AuthContext,
session: Session,
db: Database,
path: Path<PodcastPath>,
) -> cot::Result<cot::response::Response> {
let Some(user) = auth::get_request_user(&auth_ctx, &session, &db).await else {
return Ok(json_error(StatusCode::UNAUTHORIZED, "not authenticated"));
};
let Ok(podcast_id) = PodcastId::parse(&path.0.podcast_id) else {
return Ok(json_error(StatusCode::BAD_REQUEST, "invalid podcast id"));
};
let store = state.store().await?;
let fetcher = state.fetcher().await?;
match runner::refresh_now(&store, fetcher, user.id, &podcast_id, now_ms()).await {
Ok(result) => Json(RefreshResponse::from_result(result)).into_response(),
Err(error) => match error.downcast_ref::<ManualRefreshError>() {
Some(ManualRefreshError::UnknownPodcast) => {
Ok(json_error(StatusCode::NOT_FOUND, "unknown podcast"))
}
Some(ManualRefreshError::NotSubscribed) => {
Ok(json_error(StatusCode::CONFLICT, &error.to_string()))
}
Some(ManualRefreshError::TooSoon { retry_after_ms }) => {
let mut response = json_error(StatusCode::TOO_MANY_REQUESTS, &error.to_string());
response.headers_mut().insert(
RETRY_AFTER,
((retry_after_ms + 999) / 1000)
.to_string()
.parse()
.expect("digits"),
);
Ok(response)
}
None => Err(internal(format!("{error:#}"))),
},
}
}
#[derive(Debug, Serialize)]
struct SourceResponse {
episode_id: String,
/// Publisher URL; the browser streams it directly by default.
direct_url: String,
/// Same-origin proxy path, only when the proxy is enabled.
proxy_url: Option<String>,
mime: Option<String>,
}
async fn source_handler(
state: State,
auth_ctx: auth::AuthContext,
session: Session,
db: Database,
path: Path<EpisodePath>,
) -> cot::Result<cot::response::Response> {
let Some(user) = auth::get_request_user(&auth_ctx, &session, &db).await else {
return Ok(json_error(StatusCode::UNAUTHORIZED, "not authenticated"));
};
let Ok(episode_id) = EpisodeId::parse(&path.0.episode_id) else {
return Ok(json_error(StatusCode::BAD_REQUEST, "invalid episode id"));
};
let store = state.store().await?;
let Some((audio_url, mime)) = store
.audio_source(user.id, &episode_id)
.await
.map_err(internal)?
else {
return Ok(json_error(StatusCode::NOT_FOUND, "unknown episode"));
};
let (config, _) = AppConfig::load_with_db(&db).await;
let mut response = Json(SourceResponse {
proxy_url: config
.podcast_audio_proxy_enabled
.then(|| proxy_path(&episode_id)),
episode_id: episode_id.to_string(),
direct_url: audio_url,
mime,
})
.into_response()?;
response
.headers_mut()
.insert(CACHE_CONTROL, "private, no-store".parse().expect("static"));
Ok(response)
}
async fn audio_handler(
state: State,
auth_ctx: auth::AuthContext,
session: Session,
db: Database,
path: Path<EpisodePath>,
request: cot::request::Request,
) -> cot::Result<cot::response::Response> {
let Some(user) = auth::get_request_user(&auth_ctx, &session, &db).await else {
return Ok(json_error(StatusCode::UNAUTHORIZED, "not authenticated"));
};
let (config, _) = AppConfig::load_with_db(&db).await;
if !config.podcast_audio_proxy_enabled {
return Ok(json_error(
StatusCode::NOT_FOUND,
"the podcast audio proxy is disabled; stream from the publisher URL",
));
}
let Ok(episode_id) = EpisodeId::parse(&path.0.episode_id) else {
return Ok(json_error(StatusCode::BAD_REQUEST, "invalid episode id"));
};
let store = state.store().await?;
// The URL comes from this account's catalog, never from the request.
let Some((audio_url, mime)) = store
.audio_source(user.id, &episode_id)
.await
.map_err(internal)?
else {
return Ok(json_error(StatusCode::NOT_FOUND, "unknown episode"));
};
let range = request
.headers()
.get(RANGE)
.and_then(|value| value.to_str().ok());
let proxy = state.proxy().await?;
let audio = match proxy.fetch(&audio_url, mime.as_deref(), range).await {
Ok(audio) => audio,
Err(error) => {
// Neither the URL (access tokens) nor the account is logged.
tracing::info!(episode = %episode_id, "podcast proxy: {error}");
let status =
StatusCode::from_u16(error.http_status()).unwrap_or(StatusCode::BAD_GATEWAY);
return Ok(json_error(status, &error.public_message()));
}
};
let mut builder = cot::http::Response::builder()
.status(StatusCode::from_u16(audio.status).unwrap_or(StatusCode::BAD_GATEWAY))
.header(CACHE_CONTROL, "private, no-store")
.header("X-Content-Type-Options", "nosniff")
.header("Content-Security-Policy", "default-src 'none'; sandbox")
.header("Content-Disposition", "inline");
if let Some(content_type) = &audio.content_type {
builder = builder.header(CONTENT_TYPE, content_type.as_str());
}
if let Some(length) = audio.content_length {
builder = builder.header(CONTENT_LENGTH, length.to_string());
}
if let Some(content_range) = &audio.content_range {
builder = builder.header(CONTENT_RANGE, content_range.as_str());
}
if audio.accept_ranges {
builder = builder.header(ACCEPT_RANGES, "bytes");
}
let body = audio
.body
.map_err(|error| cot::Error::internal(error.to_string()));
builder.body(Body::streaming(body)).map_err(internal)
}
#[derive(Debug, Deserialize)]
struct ListQuery {
#[serde(default)]
all: Option<String>,
}
async fn list_handler(
state: State,
auth_ctx: auth::AuthContext,
session: Session,
db: Database,
query: UrlQuery<ListQuery>,
) -> cot::Result<cot::response::Response> {
let Some(user_id) = signed_in(&auth_ctx, &session, &db).await else {
return Ok(unauthorized());
};
let all = matches!(query.0.all.as_deref(), Some("1" | "true"));
let store = state.store().await?;
api_response(api::list_podcasts(&store, user_id, all).await)
}
async fn subscribe_url_handler(
state: State,
auth_ctx: auth::AuthContext,
session: Session,
db: Database,
request: cot::request::Request,
) -> cot::Result<cot::response::Response> {
let Some(user_id) = signed_in(&auth_ctx, &session, &db).await else {
return Ok(unauthorized());
};
let body = match json_body(request).await {
Ok(body) => body,
Err(error) => return Ok(api_error(error)),
};
let store = state.store().await?;
let fetcher = state.fetcher().await?;
api_response(api::subscribe_url(&store, fetcher, user_id, body, now_ms()).await)
}
/// What a `/feeds/{podcast_id}...` route does.
#[derive(Debug, Clone, Copy)]
enum PodcastRoute {
Detail,
Subscribe,
Unsubscribe,
}
async fn podcast_handler(
state: State,
route: PodcastRoute,
auth_ctx: auth::AuthContext,
session: Session,
db: Database,
path: Path<PodcastPath>,
) -> cot::Result<cot::response::Response> {
let Some(user_id) = signed_in(&auth_ctx, &session, &db).await else {
return Ok(unauthorized());
};
let podcast_id = match api::parse_podcast_id(&path.0.podcast_id) {
Ok(id) => id,
Err(error) => return Ok(api_error(error)),
};
let store = state.store().await?;
match route {
PodcastRoute::Detail => {
api_response(api::podcast_detail(&store, user_id, &podcast_id).await)
}
PodcastRoute::Subscribe => {
api_response(api::resubscribe(&store, user_id, &podcast_id).await)
}
PodcastRoute::Unsubscribe => {
api_response(api::unsubscribe(&store, user_id, &podcast_id).await)
}
}
}
async fn episodes_handler(
state: State,
auth_ctx: auth::AuthContext,
session: Session,
db: Database,
path: Path<PodcastPath>,
query: UrlQuery<EpisodeListParams>,
) -> cot::Result<cot::response::Response> {
let Some(user_id) = signed_in(&auth_ctx, &session, &db).await else {
return Ok(unauthorized());
};
let podcast_id = match api::parse_podcast_id(&path.0.podcast_id) {
Ok(id) => id,
Err(error) => return Ok(api_error(error)),
};
let store = state.store().await?;
api_response(api::episodes(&store, user_id, &podcast_id, &query.0).await)
}
/// What a `/episodes/{episode_id}/...` POST route does.
#[derive(Debug, Clone, Copy)]
enum EpisodeRoute {
Action(EpisodeAction),
Playback,
Progress,
}
async fn episode_handler(
state: State,
route: EpisodeRoute,
auth_ctx: auth::AuthContext,
session: Session,
db: Database,
path: Path<EpisodePath>,
request: cot::request::Request,
) -> cot::Result<cot::response::Response> {
let Some(user_id) = signed_in(&auth_ctx, &session, &db).await else {
return Ok(unauthorized());
};
let episode_id = match api::parse_episode_id(&path.0.episode_id) {
Ok(id) => id,
Err(error) => return Ok(api_error(error)),
};
let store = state.store().await?;
match route {
EpisodeRoute::Action(action) => {
api_response(api::episode_action(&store, user_id, &episode_id, action).await)
}
EpisodeRoute::Playback => {
let body = match json_body(request).await {
Ok(body) => body,
Err(error) => return Ok(api_error(error)),
};
let (config, _) = AppConfig::load_with_db(&db).await;
api_response(
api::playback(
&store,
user_id,
&episode_id,
body,
config.podcast_audio_proxy_enabled,
)
.await,
)
}
EpisodeRoute::Progress => {
let body = match json_body(request).await {
Ok(body) => body,
Err(error) => return Ok(api_error(error)),
};
api_response(api::progress(&store, user_id, &episode_id, body, now_ms()).await)
}
}
}
impl App for PodcastsApp {
fn name(&self) -> &'static str {
"podcasts"
}
fn router(&self) -> Router {
let refresh_state = self.state.clone();
let source_state = self.state.clone();
let audio_state = self.state.clone();
let list_state = self.state.clone();
let subscribe_state = self.state.clone();
let episodes_state = self.state.clone();
let podcast_route = |route: PodcastRoute| {
let state = self.state.clone();
move |auth_ctx: auth::AuthContext,
session: Session,
db: Database,
path: Path<PodcastPath>| {
podcast_handler(state.clone(), route, auth_ctx, session, db, path)
}
};
let episode_route = |route: EpisodeRoute| {
let state = self.state.clone();
move |auth_ctx: auth::AuthContext,
session: Session,
db: Database,
path: Path<EpisodePath>,
request: cot::request::Request| {
episode_handler(state.clone(), route, auth_ctx, session, db, path, request)
}
};
// Routes are matched in order: literal prefixes come before
// `/{podcast_id}/refresh`.
Router::with_urls([
Route::with_handler_and_name(
"/feeds",
get(
move |auth_ctx: auth::AuthContext,
session: Session,
db: Database,
query: UrlQuery<ListQuery>| {
list_handler(list_state.clone(), auth_ctx, session, db, query)
},
)
.post(
move |auth_ctx: auth::AuthContext,
session: Session,
db: Database,
request: cot::request::Request| {
subscribe_url_handler(
subscribe_state.clone(),
auth_ctx,
session,
db,
request,
)
},
),
"podcasts_feeds",
),
Route::with_handler_and_name(
"/feeds/{podcast_id}/episodes",
get(
move |auth_ctx: auth::AuthContext,
session: Session,
db: Database,
path: Path<PodcastPath>,
query: UrlQuery<EpisodeListParams>| {
episodes_handler(episodes_state.clone(), auth_ctx, session, db, path, query)
},
),
"podcasts_episodes",
),
Route::with_handler_and_name(
"/feeds/{podcast_id}/subscribe",
post(podcast_route(PodcastRoute::Subscribe)),
"podcasts_subscribe",
),
Route::with_handler_and_name(
"/feeds/{podcast_id}/unsubscribe",
post(podcast_route(PodcastRoute::Unsubscribe)),
"podcasts_unsubscribe",
),
Route::with_handler_and_name(
"/feeds/{podcast_id}",
get(podcast_route(PodcastRoute::Detail)),
"podcasts_detail",
),
Route::with_handler_and_name(
"/episodes/{episode_id}/playback",
post(episode_route(EpisodeRoute::Playback)),
"podcasts_episode_playback",
),
Route::with_handler_and_name(
"/episodes/{episode_id}/progress",
post(episode_route(EpisodeRoute::Progress)),
"podcasts_episode_progress",
),
Route::with_handler_and_name(
"/episodes/{episode_id}/restart",
post(episode_route(EpisodeRoute::Action(EpisodeAction::Restart))),
"podcasts_episode_restart",
),
Route::with_handler_and_name(
"/episodes/{episode_id}/played",
post(episode_route(EpisodeRoute::Action(
EpisodeAction::MarkPlayed,
))),
"podcasts_episode_played",
),
Route::with_handler_and_name(
"/episodes/{episode_id}/unplayed",
post(episode_route(EpisodeRoute::Action(
EpisodeAction::MarkUnplayed,
))),
"podcasts_episode_unplayed",
),
Route::with_handler_and_name(
"/episodes/{episode_id}/source",
get(
move |auth_ctx: auth::AuthContext,
session: Session,
db: Database,
path: Path<EpisodePath>| {
source_handler(source_state.clone(), auth_ctx, session, db, path)
},
),
"podcasts_episode_source",
),
Route::with_handler_and_name(
"/episodes/{episode_id}/audio",
get(
move |auth_ctx: auth::AuthContext,
session: Session,
db: Database,
path: Path<EpisodePath>,
request: cot::request::Request| {
audio_handler(audio_state.clone(), auth_ctx, session, db, path, request)
},
),
"podcasts_episode_audio",
),
Route::with_handler_and_name(
"/{podcast_id}/refresh",
post(
move |auth_ctx: auth::AuthContext,
session: Session,
db: Database,
path: Path<PodcastPath>| {
refresh_handler(refresh_state.clone(), auth_ctx, session, db, path)
},
),
"podcasts_refresh",
),
])
}
}
#[cfg(test)]
mod tests {
use super::*;
fn request(content_type: Option<&str>, body: &'static str) -> cot::request::Request {
let mut builder = cot::http::Request::builder()
.method("POST")
.uri("/api/podcasts/feeds");
if let Some(value) = content_type {
builder = builder.header(CONTENT_TYPE, value);
}
builder.body(Body::fixed(body)).unwrap()
}
#[tokio::test]
async fn json_bodies_need_the_json_content_type() {
let url = r#"{"url": "https://podcasts.example/feed.xml"}"#;
for content_type in [
"application/json",
"application/json; charset=UTF-8",
"Application/JSON",
] {
let body = json_body(request(Some(content_type), url)).await.unwrap();
assert_eq!(body["url"], "https://podcasts.example/feed.xml");
}
// What a page can send cross-origin without a CORS preflight.
for content_type in [
Some("text/plain"),
Some("text/plain;charset=UTF-8"),
Some("application/x-www-form-urlencoded"),
Some("multipart/form-data; boundary=x"),
None,
] {
let error = json_body(request(content_type, url)).await.unwrap_err();
assert_eq!(error.status, 415, "{content_type:?}");
}
// An empty body (a plain POST) is an empty object whatever the type.
let empty = json_body(request(None, "")).await.unwrap();
assert_eq!(empty, serde_json::json!({}));
let malformed = json_body(request(Some("application/json"), "{"))
.await
.unwrap_err();
assert_eq!(malformed.status, 400);
}
}