From 5aaea8a8eb475f753f2d8d63ac0d37dc47ac84a4 Mon Sep 17 00:00:00 2001 From: Sanapach Date: Thu, 19 Nov 2026 20:24:30 +0200 Subject: [PATCH] Document podcast feed refresh and the audio proxy Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 16 ++++++++++++++++ docs/administration.md | 22 ++++++++++++++++++++++ docs/development.md | 40 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 78 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3e31554..f581897 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,22 @@ it; the wire behavior towards other devices is unchanged. Migrations `m_0056` and `m_0057` import the state that 0.13 relayed (`furumusic__fed_podcast_relay`, kept but unused). +- Refresh subscribed podcast feeds in the background (`podcast_refresh` job, + every five minutes; each feed about hourly) with conditional requests, + permanent redirects learned as feed aliases, size and time limits and an + exponential backoff up to a day on errors. Accounts subscribed to the same + feed share one request. `POST /api/podcasts/{podcast_id}/refresh` refreshes + one feed on demand. Only metadata is fetched, never audio. +- Optional podcast audio proxy (`podcast_audio_proxy_enabled`, off by + default; browsers stream from the publisher otherwise): + `GET /api/podcasts/episodes/{episode_id}/audio` streams an episode of the + signed-in account from its publisher with Range pass-through, audio content + types only and size/time limits. `GET /api/podcasts/episodes/{episode_id}/source` + tells the player which URLs to use. +- Feed and proxy requests only reach public addresses: names are resolved and + checked once per connection (no DNS rebinding), IP literals and every + redirect hop are checked, and no cookies, credentials or system proxies are + used. ## v0.13.0 — 2026-11-19 diff --git a/docs/administration.md b/docs/administration.md index 1a40901..8f013ce 100644 --- a/docs/administration.md +++ b/docs/administration.md @@ -79,6 +79,28 @@ them. A device that does not support podcasts yet (device-sync protocol below it as the playback device shows that it needs an update, and the episodes stay in the queue. Jam guests see podcast episodes of the host only as private items. +### Podcast feeds and audio + +The `podcast_refresh` job (every five minutes, listed under Jobs) checks the +feeds of subscribed podcasts: each feed about once an hour with conditional +requests, failing feeds less and less often (up to once a day). It downloads +feed metadata only, never episode audio. A failing feed keeps its known +episodes. Accounts subscribed to the same feed share one request. + +The server therefore makes outgoing HTTP(S) requests to podcast publishers. +It only connects to public addresses: feed or audio URLs that point to +loopback, private, link-local, CGNAT or cloud metadata addresses, directly, +through DNS or through a redirect, are refused. System proxy settings are not +used for these requests. + +Episode audio is streamed by the browser directly from the publisher. Some +publishers cannot be played that way (no CORS, or plain HTTP while this +server uses HTTPS). For them, enable **Settings → Podcasts → Podcast audio +proxy** (`FURU_PODCAST_AUDIO_PROXY_ENABLED=true`): the server then fetches +the audio of an episode from the publisher when a signed-in user's player +requests it and passes it through without storing it. This uses the server's bandwidth. Only +audio responses are passed through, up to 1 GiB and 4 hours per request. + ### Upgrading from 0.13 Podcast state synchronized from other Furumi players is kept in per-account diff --git a/docs/development.md b/docs/development.md index cadfddf..27688cc 100644 --- a/docs/development.md +++ b/docs/development.md @@ -101,6 +101,46 @@ create the tables and import what 0.13.0 kept in `furumusic__fed_podcast_relay` episode references in the operation log. The relay table is no longer written or read; it stays until a later cleanup release. +### Feed refresh and audio delivery + +The runtime around the store lives next to it in `src/podcasts/`: + +- `net.rs` — `SafeHttp`, the only HTTP client for podcast feeds and audio. + It accepts `http`/`https` URLs without userinfo, resolves names with + `GuardedResolver` and refuses the whole answer when any address is not + public (loopback, RFC 1918, CGNAT, link-local, cloud metadata, unique local, + multicast, unspecified, documentation, reserved; IPv4-mapped, NAT64 and + 6to4 addresses are judged by their IPv4 part). The connector connects to + exactly the checked addresses, so a second DNS answer cannot be swapped in. + IP literals are checked before connecting, redirects are followed manually + (each hop checked, at most 5), and system proxies, cookies and `Referer` + are disabled. +- `fetch.rs` — `FeedFetcher`: conditional GET (`If-None-Match`, + `If-Modified-Since`), `Accept-Encoding: identity`, 32 MiB and 60 s limits, + `Retry-After` on 429/503, the shared `music_dht` parser. Only a chain of + permanent redirects (301/308) moves a feed. +- `runner.rs` — scheduling: `podcasts_due_for_refresh`, one request per feed + URL for all accounts subscribed to it (conditional only when they share the + same validators), `apply_feed`, then the fetch state. Healthy feeds are + checked hourly plus a stable spread of up to 10 minutes; failures back off + 15 min × 2ⁿ⁻¹ up to a day (a longer `Retry-After` wins). `refresh_now` is + the manual refresh: subscribed podcasts only, at most every 30 s. + `jobs/podcast_refresh.rs` runs `refresh_due` every five minutes (200 + podcasts, 4 requests in flight, one run at a time via an advisory lock). +- `proxy.rs` and `http.rs` — the optional audio proxy and the endpoints under + `/api/podcasts`. The proxy takes an episode id, loads the URL from the + account's catalog (`PodcastStore::audio_source`), forwards a single + sanitized byte `Range`, passes 200/206/416 through, accepts audio content + types only (a generic binary type is replaced by the stored enclosure type + or the URL extension), and stops at 1 GiB, 20 s without headers, 30 s + without data or 4 h per response. It is off unless + `podcast_audio_proxy_enabled` is set; by default the browser streams from + the publisher URL. + +Tests never reach the internet: `test_server.rs` serves on 127.0.0.1 and +provides a scripted resolver. Loopback is reachable only through +`AddressPolicy::test_allow_loopback`, which exists only under `#[cfg(test)]`. + Everything sent to a device is gated by the version that device reported itself (`profile_protocol_version`; relayed profiles only raise it). See the podcast contract (`PODCASTS.md`) and `PLAYBACK_PROTOCOL.md` in the Frid repository.