The prototype kept one row per enclosure URL for GUID-less items, so stale rows could change which identity key is unique and give imported episodes ids a fresh device never derives. The import now collapses rows of one item seen under several enclosure URLs, and the first refresh re-keys imported GUID-less episodes without progress or sessions to the ids the current feed gives. Fetch-state writes read and write the row under one lock and one immediate transaction, so concurrent writers no longer lose columns or failure counts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
furumi-library
Client-independent persistence foundation for Furumi music players.
The crate owns the shared library.db contract: SQLite schema and migrations,
catalog models and queries, local import and metadata extraction, artwork
resolution, playlists, likes, listening history, and similarity index storage.
It contains no UI, playback engine, or application runtime.
During local development clients use a path dependency:
furumi-library = { path = "../frid/crates/furumi-library" }
Adjust the relative path to match the position of the client repository. After publication, clients can depend on the released crate version instead.
Library::open(default_db_path()?) opens the same platform-native Furumi
library used by every client. Connections use WAL, foreign keys, and a busy
timeout so independently running clients can safely share the database.
Version 0.3 follows music-dht 0.6, whose device-sync and podcast contract
types it re-exposes.
Podcasts
furumi_library::podcasts::PodcastStore is the SQLite reference store of the
podcast contract (workspace PODCASTS.md, section "SQLite reference store").
It lives in its own file, conventionally podcasts.sqlite3
(PODCAST_DB_FILE) next to library.db; the caller passes the path.
- Migrations run on
PRAGMA user_version, each in its own transaction. A database of the original podcast prototype (user_version1) is imported: its tables are renamedlegacy_podcasts/legacy_podcast_episodes(never dropped), feeds become subscriptions with contract ids, rows that cannot be imported are listed inlegacy_quarantine. A database from a newer Furumi, or a file that is not a podcast database, is refused without being touched. - Local actions (
subscribe,unsubscribe,set_shared,start_session,checkpoint,seek,restart,complete_session,mark_played,mark_unplayed,record_listen_session) draw stamps from aStampSource(usually the client's sync log), apply the operation and returnPodcastLocalOps to append to the log with exactly those stamps. - Sync:
apply_remote_opapplies the fivepodcast_*operations,fill_snapshot/export_snapshotproduce the bounded snapshot sections andapply_snapshotmerges them. Everything goes through themusic-dhtmaterializers and merge functions, so the result does not depend on delivery order and never loses newer local state. - RSS:
apply_feedingests a document parsed bymusic_dht::podcast::feed(the crate enables thepodcast-feedfeature): channel metadata, episodes with stable ids and current audio URLs, feed aliases from permanent redirects anditunes:new-feed-url. It never touches subscriptions, progress or history. HTTP, conditional requests and scheduling stay in the client;record_fetch_*,fetch_stateandpodcasts_due_for_refreshkeep the local-only fetch state, which is never synced. - Queries:
list_podcasts,seasons,episodes(season, played-state and text filters, date or episode-number order),resume_position_ms,episode_ref/episode_trackfor queueing,listen_history.
The store is synchronous: methods take &self and lock one connection, so
Arc<PodcastStore> can be shared; run calls on a blocking pool.
TrackItem.podcast marks a queue item as a podcast episode
(TrackItem::podcast_episode). Music-only code (likes, playlists, history,
content ids, federation downloads) must check TrackItem::is_podcast; the
music library never stores episodes. As a fail-safe for older code, podcast
items have a negative per-episode id (TrackItem::podcast_track_id, at
most PODCAST_TRACK_ID_MAX) and release_id / artist id -1, like pending
federated tracks.