diff --git a/CHANGELOG.md b/CHANGELOG.md index 32ce08a..3e31554 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/docs/administration.md b/docs/administration.md index 1c7e615..1a40901 100644 --- a/docs/administration.md +++ b/docs/administration.md @@ -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 diff --git a/docs/development.md b/docs/development.md index 7bb4238..cadfddf 100644 --- a/docs/development.md +++ b/docs/development.md @@ -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 = :`) 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 ```