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

+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
```