Document podcast feed refresh and the audio proxy
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
2c0c3d21aa
commit
5aaea8a8eb
3 files changed
+78
No files matched your search
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user