Document podcast feed refresh and the audio proxy

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-20 15:12:38 +02:00
1 parent 2c0c3d21aa
commit 5aaea8a8eb
3 files changed
+78

No files matched your search

+40
View File
@@ -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.