Document the podcast store and the relay import

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 681ff7af89
commit c2627444c5
3 files changed
+68 -9

No files matched your search

+10
View File
@@ -1,5 +1,15 @@
# Changelog
## Unreleased
- Store podcast subscriptions, feed aliases, episodes, seasons, progress and
listening sessions of each account in PostgreSQL (`src/podcasts/`), with
the shared `music-dht` podcast rules. Received podcast operations and
snapshot sections are applied to this store, and snapshots are built from
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).
## v0.13.0 — 2026-11-19
- Use the shared `music-dht` 0.6 device-sync types and announce device-sync
+9
View File
@@ -79,6 +79,15 @@ 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.
### Upgrading from 0.13
Podcast state synchronized from other Furumi players is kept in per-account
podcast tables (`furumusic__podcast*`). The upgrade imports what 0.13 kept in
`furumusic__fed_podcast_relay`; that table is no longer used and can be
dropped by a later release. Release 0.13 does not read the new tables: after
a rollback it would serve the relay table as it was at the upgrade, and
devices would send their newer podcast state again in their snapshots.
### Rolling back to 0.12
Release 0.13 relays podcast synchronization operations from other Furumi
+49 -9
View File
@@ -38,13 +38,12 @@ Update the pinned build tools in `Dockerfile`; changing them rebuilds the cache.
## Connected devices and podcast queue items
Trusted-device sync uses the shared `music_dht::device_sync` types (no local
copies) and announces protocol version 4. The web player has no podcast
features yet, but it keeps every v4 element it receives:
copies) and announces protocol version 4. Each account is one virtual device:
- podcast operations stay in the operation log and are relayed to v4 devices
only; their registers and the podcast snapshot sections are merged with the
shared `music_dht::podcast` rules into `furumusic__fed_podcast_relay`
(opaque contract JSON) and returned in this server's snapshots;
only. They are also applied to the account's podcast store
(`src/podcasts/`, `PodcastStore`), which also provides the podcast snapshot
sections;
- queue items that are not library tracks become external browser items
(`source` plus the verbatim `wire_track`), so podcast episodes and Jam
placeholders survive peer → server → browser → server → peer unchanged;
@@ -55,23 +54,64 @@ features yet, but it keeps every v4 element it receives:
placeholders are never stored in a user's own queue.
- a browser that selects a podcast episode it cannot play does not know the
episode's position. It reports `position_unknown`, and the server sends the
resume position of the relayed progress register instead of 0. Jam
resume position of the episode's progress register instead of 0. Jam
participant commands carry `jam_participant`; the host browser checks them
against its own queue.
Rolling back to 0.12 needs the podcast operations removed from the operation
log first; see "Rolling back to 0.12" in `administration.md`.
### Podcast store
`PodcastStore` implements the podcast contract of `music_dht::podcast`
(Frid `PODCASTS.md`) on PostgreSQL, with the invariants of the SQLite
reference store in `furumi-library`; every table has a `user_id` key.
| Table | Content | Synced |
| --- | --- | --- |
| `furumusic__podcast` | channel metadata, fetch URL | no (catalog) |
| `furumusic__podcast_feed_alias` | bounded grow-only alias set | in subscription records and `podcast_feed_aliases_added` |
| `furumusic__podcast_episode` | `EpisodeMeta`, `source` `feed`/`sync`, `in_feed`, cached search text | no (catalog) |
| `furumusic__podcast_season` | view over the episodes | no |
| `furumusic__podcast_subscription`, `_share`, `_progress` | registers | yes |
| `furumusic__podcast_listen_session` | grow-only set of sessions | yes |
| `furumusic__podcast_fetch_state` | ETag, Last-Modified, check times, errors, cover cache | never |
- One apply path: received operations, snapshot records and local actions go
through the `SyncOpWire` materializers and the `merge_*` functions of
`music_dht::podcast`. Each write transaction holds a per-account advisory
lock.
- Local actions (`subscribe`, `unsubscribe`, `set_shared`, `start_session`,
`checkpoint`, `seek`, `complete_session`, `restart`, `mark_played`,
`mark_unplayed`, `record_listen_session`) append their operation to the
account's sync log with the next stamp (`devices::append_local_op`: `seq`,
`hlc_ms`, `op_id = <device>:<seq>`) and apply exactly that operation in
the same transaction.
- `apply_feed` resolves episode ids with the shared no-GUID rule against the
stored episodes, including those only known from synced references. It
updates the catalog and the alias set, never a register, progress or a
session.
- Snapshots export each section newest first up to its count and bound it
with `bound_podcast_state_to`. The catalog and the fetch state are never
exported.
Migrations `m_0056_create_podcast_store` and `m_0057_import_podcast_relay`
create the tables and import what 0.13.0 kept in `furumusic__fed_podcast_relay`
(registers as contract JSON, already merged) plus the catalog rows of the
episode references in the operation log. The relay table is no longer written
or read; it stays until a later cleanup release.
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.
```bash
cargo test devices:: queue_items podcast_relay queue_persistence
cargo test devices:: queue_items podcasts:: queue_persistence
node --test tests/player_queue_sources.test.cjs
# Migrated disposable PostgreSQL (start the server against it once):
# Disposable PostgreSQL; the tests run the production migrations on it, and
# the migration test creates and drops a database next to it:
FURU_DEVICE_SYNC_TEST_DATABASE_URL=postgresql://... \
cargo test devices::postgres_tests -- --ignored
cargo test postgres_tests -- --ignored
FURU_METADATA_FIX_TEST_DATABASE_URL=postgresql://... \
cargo test undo_accepts_playback_archives_written_before_the_typed_queue -- --ignored
```