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

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