Compare commits

...
169 Commits
Author SHA1 Message Date
Aleksandr Bogomiakov 038f0979af Release Furumi 0.5.0 with published FRID podcast crates 2026-11-20 14:17:49 +00:00
ab 81f422b244 Merge pull request 'Публичные подкасты в TUI: «Поделиться», поиск с типом podcast и «Подписаться» из карточки (MR-T3)' (#4) from sanapach/furumi-tui:podcasts/discovery into federation 2026-11-20 14:11:11 +00:00
ab 7659313dc2 Merge pull request 'Подкасты в TUI на контракте FRID: подписки, воспроизведение, прогресс, синхронизация устройств v4 (MR-T2)' (#3) from sanapach/furumi-tui:podcasts/tui into federation 2026-11-20 14:11:09 +00:00
ab 44d0bb5abe Merge pull request 'Порядок вкладок 1–6 с Podcasts на 4 и миграция keymap (MR-T1)' (#2) from sanapach/furumi-tui:podcasts/tab-order into federation 2026-11-20 14:11:00 +00:00
sanapachandClaude Opus 5.5 59d6a1fe24 Point frid deps at the fork branch
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:15 +02:00
sanapachandClaude Opus 5.5 409188b9a9 Publish podcast cards only after the first device sync
A device restarted with a "share" decision that another device of its
group revoked meanwhile sent that card again: the first reconciler pass
called sync_shares from the stale registers before device sync ran.
Until DeviceSync says the registers are current (a sync exchange with a
v4 device of the group after the store was attached, or no such device
to wait for), passes now only unpublish cards the local registers no
longer share and never call sync_shares.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 ce5697ce1d Document held-back revocation and quitting during a revocation
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 adfe809a40 Wait for in-flight revocations and track them with federation off
Share-off and unsubscribe now take a revocation ticket on the UI thread
before the write starts and ask for the immediate pass from the blocking
task once the write succeeded, so quitting right after Shift+F (before the
write's event was handled) still waits for the tombstone. With the
federation off or not started yet, a podcast that was shared counts as
possibly not revoked: the reconciler keeps it in the Off reports until the
overlay runs, the side panel says the card may not be revoked yet, and the
quit-time flush logs a warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 d6962eba47 Keep public artwork whose path only looks random
Public podcast hosts and CDNs name artwork and pages by UUIDs and
content hashes, so the random-looking path rule dropped the artwork of
most public podcasts. Artwork and links now follow the query and host
rules only; a member feed's artwork is still left out with its feed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 43e0696531 Drop share confirmations whose decision was not written
A confirmation is recorded as pending before the share decision is
written and covers the next newer decision. When the write failed (the
podcast was unsubscribed by a sync meanwhile, a database error), the
pending entry stayed and later covered a decision taken on another
device that this user never saw. Put the previous entry back on failure,
and drop pending entries left in the file by a call that never finished.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 405f8ae6d3 Hold back unconfirmed private-looking cards before syncing
FRID's sync_shares keeps publishing a card whose feed URLs this device
already publishes, even without the privacy confirmation. A device that
missed an intermediate share-off would go on publishing a private-looking
URL nobody confirmed for the new decision. share_plan now leaves such a
podcast out of the states, so sync_shares revokes the old card, and
reports it as held back itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 3ddf7995e8 Document prompt revocation and moved-feed subscriptions
README, ARCHITECTURE, CHANGELOG and AGENTS describe the immediate
revocation and quit-time wait, decision-bound confirmations, the card
URL filter, devices that left the group, the separate bounded podcast
search, and which direction of a moved feed the search mark covers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 17ed8bfcd4 Scroll the podcast card exactly to its end
The card and the share dialog measure their word-wrapped height the
way it is rendered (ratatui's rendered-line-info), and scroll keys stop
at the last line instead of running past it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 fd6827126f Recognize subscriptions under a feed's newer address
Subscribing to an older address whose feed announces a newer one this
device already follows (itunes:new-feed-url without a redirect) reports
the existing subscription instead of adding a second one, and a card
whose feed moved to a followed address reads «Уже подписан» once its
episodes were read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 744d56e06b Leave private-looking artwork and links out of cards
The share dialog shows the feed URLs only, so a card no longer carries
an artwork or web page URL that looks like it holds an access key, and
a member feed's card carries neither.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 7add66920d Bind share confirmations to the share decision
A privacy confirmation now covers the share decision it was given for,
not only the URLs: sharing turned off, or turned on again after a
revocation, on any trusted device drops it, so this device asks again
before it publishes a feed URL that looks private.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 1137670229 Revoke podcast cards promptly and report unrevoked ones
Turning sharing off or unsubscribing runs a reconciler pass right away,
and quitting waits up to 4 s for it. The Podcasts tab tells a private
podcast whose card from this device is still live, failed revocations
are reported without ids, the overlay peer count stays current, and the
reconciler loop is tested against a loopback overlay.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 a51f5552e3 Search public podcasts apart from the music search
Federated music results no longer wait for the discovery overlay: the
podcast search runs as its own task, bounded at 15 s including the
overlay's bootstrap, and arrives as its own event.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 d38144fe45 Document finding public podcasts and bump to 0.5.0
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 160237b5a5 Test subscribing from a public podcast card
Cover the merge order of podcast hits, alias resolution, the feed
preview, subscribing from a card (same podcast id as by URL, never a
claimed URL, forged ids refused) and an end-to-end run: a stranger's
node finds a shared card over loopback overlay nodes, subscribes
privately, refreshes from a local feed server and keeps the
subscription after the publisher stops sharing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 e038f282c2 Find public podcasts in search and subscribe from their cards
Federated search also queries the podcast discovery overlay and lists
the podcast entries of merge_search_results after the music results,
marked [podcast], with the publishing devices or "subscribed" (also
through a feed alias resolved off the UI thread). Enter opens the card:
the publishers' claims, the origin feed URL, unverified moved-feed
claims, an optional episode preview read from the feed itself, and
«Подписаться», which subscribes privately with the origin URL only.
«Уже подписан» opens the podcast in the Podcasts tab instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 25a9f2b0ec Subscribe to a parsed feed URL
Split refresh::subscribe into input parsing and subscribe_url, so a
public card's origin URL can be subscribed to exactly as given, and let
the feed parser be reused for previews.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 6d225531a5 Document sharing podcasts in the federation
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 8f4e58d8af Add a share toggle to the Podcasts tab
Shift+F in the podcasts context shares the selected or opened podcast
through PodcastStore::set_shared (a synced decision) or makes it private
again. A feed URL that looks private is confirmed first in a dialog that
lists the warnings in Russian. The reconciler runs after share and
unsubscribe actions, received podcast operations, feed refreshes, overlay
restarts and periodically; the list and side panel show the shared and
published state and publication errors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 8c90035fa2 Reconcile own podcast publications with the share registers
podcasts::publication builds one PodcastShareState per subscription (cards
from the catalog for shared podcasts only, the device-local privacy
confirmation) and hands them to PodcastDht::sync_shares, which publishes
what is shared and tombstones the rest. Without a readable store every own
card is revoked. Privacy confirmations live in a 0600 JSON file next to
podcasts.sqlite3 and cover exactly the confirmed URLs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 c453b0a52f Run the podcast discovery overlay in the federation node
The node serves FRID's podcast_dht overlay next to the similarity overlay
(cache federation/podcast-dht.sqlite3), runs its maintenance, hands peer
capability manifests to note_peer_capabilities and advertises podcast_dht
only while the overlay runs. A cache that cannot be opened is logged and
only turns discovery off. The running overlay is exposed through a watch
channel for the publication reconciler.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:13:07 +02:00
sanapachandClaude Opus 5.5 ea7cdc4b7f Point frid deps at the fork branch
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:12:14 +02:00
sanapachandClaude Opus 5.5 c7e6a3672d Test that an older Jam guest cannot drop the host's episodes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 01:51:02 +02:00
sanapachandClaude Opus 5.5 e0624ab7f4 Document what an older device's takeover does to a podcast queue
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 22:15:09 +02:00
sanapachandClaude Opus 5.5 2806e679ac Leave out placeholders an older device echoes back as music
A device below sync v4 mirrors the redacted queue it gets with its own
types, which drop PlaybackTrack::source, so each "Private item" becomes
a bare music item. When it takes playback over (Play on it, a
paused-startup claim, automatic failover) or sends a command, it
announces those items, and this device adopted unplayable fake tracks
and passed them on to every v4 peer. States from such devices are now
cleaned on receipt, with a status message once per change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 22:15:09 +02:00
sanapachandClaude Opus 5.5 d03a3300f1 Resume dropping prototype feed validators after an interrupted start
The prototype import commits inside PodcastStore::open and the imported
validators were dropped afterwards, once. A start that stopped in
between left them for good. A marker next to the store, written before
the import and removed once every podcast was handled, makes the step
run again at the next start. The imported failure count is recorded
again as it was, so the back-off is kept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 22:12:24 +02:00
sanapachandClaude Opus 5.5 42ecc310fc End a sizeless episode stream where it ends when only the feed knew its length
A stream without a file size whose decoder cannot measure its duration
only has the feed's itunes:duration, which is often longer than the
audio. Treat that duration as a hint: a clean close past 80 % of it is
the end. A duration the decoder measured keeps the strict completion
window. The interrupted message for a stream that cannot seek now says
to start over or mark the episode played instead of "press play".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 22:11:33 +02:00
sanapachandClaude Opus 5.5 96e615bf1d Refuse an episode seek without leaving the effect early
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 21:56:12 +02:00
sanapachandClaude Opus 5.5 34c096a36b Bound a whole feed fetch and test the fetch limits
A slow server could hold one of the four refresh slots for 60 s per
redirect hop. A feed or cover fetch now has an overall deadline (120 s).
Tests cover feeds over the size cap with and without Content-Length
(error recorded with back-off, catalog kept), the redirect cap, a
redirect loop, a non-http redirect, a hanging server, and covers (not an
image, over the cap, written atomically). The test server can stall.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 21:53:44 +02:00
sanapachandClaude Opus 5.5 268ea915da Keep podcast store work in sync handlers off Tokio workers
The device-sync stream handlers exported and merged podcast snapshot
sections and operations synchronously on a Tokio worker. While a large
feed refresh held the store (up to about half a second), the worker's
other tasks (feed checks, streams, art) waited. Run that work in
block_in_place on the multi-thread runtime, and say so in ARCHITECTURE.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 21:52:05 +02:00
sanapachandClaude Opus 5.5 e0da2ddf2b Move a feed to its permanent address behind a temporary redirect
A 301 to a new host followed by a 302 (CDN, tracker) never moved the
feed, because only all-permanent chains counted; every check then went
through the old address without validators and re-applied the whole
feed. The target of the leading permanent hops is now recorded as the
new fetch URL (the old one becomes an alias); the document is still
parsed against the URL that served it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 21:50:44 +02:00
sanapachandClaude Opus 5.5 fe373e4169 Parse imported prototype feeds on their first check
The prototype import keeps the prototype's ETag and Last-Modified, but
the prototype stored no seasons, episode numbers or types, and GUID-less
episodes stay provisional until the feed is parsed again. The first check
was answered 304 and a feed that no longer changes was never parsed.
Drop the imported validators right after the migration so the first
check downloads and applies the feed. Contract gap for the FRID import.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 21:49:16 +02:00
sanapachandClaude Opus 5.5 42f22f0fea Document lost connections, cancellation and seeks of episodes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 21:47:41 +02:00
sanapachandClaude Opus 5.5 2989747162 Stop broken episode streams instead of completing them
- The stream reader records whether the decoder stopped on a read error
  and whether the server announced the file size. An episode whose
  connection was lost (stall, expired URL) or whose sizeless stream
  closed early is no longer completed at its full duration: the last
  position is saved, playback stops on the episode and the queue does
  not move on (playback::played_to_the_end).
- Streams are cancelled by the player's source generation: a superseded
  start stops connecting or reading up to its resume offset, and a read
  blocked inside the audio callback returns within 100 ms instead of up
  to 30 s. The player no longer reports the end of a superseded source.
- A pause or resume pressed while an episode connects is applied when
  its source arrives (Controller::expect_source).
- Seeks report their result (PlayerEvent::Seeked); an episode's seek is
  saved only when the audio moved, and seeks while connecting or in a
  stream without Range support are refused with a message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 21:47:41 +02:00
sanapachandClaude Opus 5.5 8d87fe3959 Keep older devices hearing from a podcast queue owner
A device below sync v4 got no playback snapshot while the queue held an
episode, so its engine never heard the owner's heartbeat and took
playback over by automatic failover after two minutes; this device then
adopted its queue and the episodes were gone. Send such peers the
coordination envelope with the queue redacted like for Jam: every
episode becomes an opaque "Private item", nothing is stripped, and their
commands stay refused while the queue has episodes.

This departs from FRID PLAYBACK_PROTOCOL.md rule 1 ("send None") and is
reported as a contract gap.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 21:40:07 +02:00
sanapachandClaude Opus 5.5 70df945ada Keep podcast URLs out of the personal-sync debug log
Podcast operations and playback commands with episodes carry feed and
audio URLs that may hold private tokens; the Logs tab shows this crate's
debug output. Log only their kind.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 21:39:19 +02:00
sanapachandClaude Opus 5.5 a79f0a0e95 Save a seek from a controlling device as an explicit episode action
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 21:03:55 +02:00
sanapachandClaude Opus 5.5 c6d7848ba4 Document podcast sync between devices and release 0.4.0
README explains that podcast state is private by default, syncs only
between trusted devices and streams audio from the publisher, plus
handoff, Jam and older devices. ARCHITECTURE, AGENTS and the changelog
describe protocol v4, version gating, the podcast store bridge and the
invariants (no numeric ids for episodes, versions only from the device
itself).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 21:02:45 +02:00
sanapachandClaude Opus 5.5 a92e12f322 Hand off podcast queues to v4 devices and keep episodes private in Jam
Queue items now cross the wire with their explicit source: episodes as
PlaybackSource::PodcastEpisode, received ones as TrackItem episodes, and
the source mode filter never drops them. A handoff carries the episode,
position and pause; an episode that becomes current at position 0
resumes from its saved position. A podcast queue is not handed to a
device below v4 (it needs an update), and playback commands from such a
device are ignored while the queue has episodes. Controlling a v4 device
may queue episodes.

Jam hosts publish redacted snapshots, so guests see numbered private
placeholders. Guest commands that add episodes are dropped; their
placeholders are mapped back to the host's episodes, and changes that
drop or duplicate them, or seek in them, are refused. A guest leaving a
Jam drops the placeholders.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 21:00:39 +02:00
sanapachandClaude Opus 5.5 79372e00fc Sync podcast state with devices on protocol v4
This client now announces device-sync protocol 4. Podcast operations
are applied to the podcast store, kept in the log and relayed; those
that arrive before the store opens wait in sync_podcast_pending.
Snapshots carry the podcast sections, bounded by the shared limits and
by the line budget of each message, and are merged after the operations.
Operations, snapshot sections and playback state that need v4 are only
sent to peers that reported v4. Periodic progress checkpoints are
coalesced in the log, and the Podcasts tab reloads after changes from
other devices.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 20:54:16 +02:00
sanapachandClaude Opus 5.5 4c3edbcd12 Store peer protocol versions as the peers report them
A device_profile_set and the pending pairing row used to store this
build's own protocol constant for another device, which would defeat
version gating. Self-reports (hello, pairing, the sender's own entry of a
devices list, its own profile announcement) now replace the stored
version and relayed profiles only raise it. Invites and profile
announcements carry the version, and the first start of a new version
announces it in the log.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 20:44:14 +02:00
sanapachandClaude Opus 5.5 e7713269f2 Use the shared device-sync wire types
The private copies of the device-sync wire types are replaced by
music_dht::device_sync. Golden tests keep the furumi-tui 0.3.x types
verbatim and check that v3 messages serialize byte for byte the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 20:41:11 +02:00
sanapachandClaude Opus 5.5 253583b139 Complete episodes after a seek into their last seconds
The progress tracker's observation step is now a pure method with tests
for listening time (jumps and pauses do not count), pause saves, the
checkpoint interval and one-time completion. A seek no longer marks the
playback completed by itself, so seeking into the last seconds still
sends complete_session on the next tick. The episode list render test
covers the live position of the playing episode.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 20:30:11 +02:00
sanapachandClaude Opus 5.5 54db2978e0 Document episode playback, queue identity and progress saving
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 20:28:36 +02:00
sanapachandClaude Opus 5.5 9321e82335 Play podcast episodes from the queue and save their progress
Episodes stream from the publisher through the prototype's bounded HTTP
Range reader (ported, URL queries redacted from errors). The audio URL and
resume position come from the store at play time; a 4xx on the audio URL
refreshes the feed once and retries with the address it now lists, and a
stream that cannot seek refuses to start at a saved position instead of
playing from the wrong place. Prepared sources reach the audio thread
with the player's source generation, so a slow stream never replaces a
newer start or stop, and with their start offset for position reporting.

Progress follows the FRID contract through one ordered writer thread:
start_session or restart on start, checkpoints every 20 s and on pause,
explicit seeks, complete_session near the end or at end of stream, and a
final save with the last seen position on stop, track change, handoff
and exit. A superseded session stops checkpointing until the next
explicit action; listening sessions are recorded at pause, completion
and end. Enter on an episode plays it after the current item, b starts
it over, a/A queue it, and mark played goes through the same writer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 20:28:36 +02:00
sanapachandClaude Opus 5.5 3567f5f395 Key queue items by source and keep episodes out of music-only paths
Podcast episodes share the sentinel id -1, so the queue key now checks
the episode id first (ep:...) and falls back to TrackItem::key instead of
local:{id}. Likes, playlists, metadata edits, music history, content-id
lookups, share links, similarity and artist/release jumps skip episodes;
Shift-J and the info popup open the podcast instead. Sync protocol 3
cannot carry episodes, so peers and Jam guests get the private-item
placeholder, handoff of a queue with episodes is refused and remote
SetState commands do not replace such a queue.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 20:12:01 +02:00
sanapachandClaude Opus 5.5 7583afaeba Box large AppEvent payloads after TrackItem grew
furumi-library 0.3.0 adds TrackItem.podcast, which makes TrackItem a few
hundred bytes larger. Box the track-info result and the federation status
in AppEvent so the event enum stays small (and clippy's
large_enum_variant does not fire on it).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 20:00:36 +02:00
sanapachandClaude Opus 5.5 043caf1aaf Document podcast subscriptions and their runtime boundaries
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 19:58:37 +02:00
sanapachandClaude Opus 5.5 99c4d05dec Replace the Podcasts placeholder with subscriptions, seasons and episodes
The tab opens the FRID podcast store (podcasts.sqlite3, migrating a
prototype database in place; newer or foreign files are reported and left
unchanged) off the UI thread and shows subscriptions with unplayed counts
and check status, podcast -> seasons -> episodes navigation, and episodes
with saved position, played state, duration and date. Episode search,
played filter and order run as paged store queries with request sequence
numbers. Adding a feed, checking one or all feeds, marking played and
unsubscribing (with a confirmation that progress is kept) go through
Effect/AppEvent; a scheduler refreshes due feeds in the background.

New actions are bound in the podcasts keymap context and listed in a
Podcasts help section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 19:58:37 +02:00
sanapachandClaude Opus 5.5 07dcd0587c Fetch podcast feeds and stamp store actions from the sync log
Add src/podcasts: an HTTP client with conditional requests, hand-followed
redirects (permanent ones become feed aliases via PodcastStore::apply_feed),
size and time limits and a furumi user agent; subscribe and refresh flows
that parse feeds with the shared music-dht parser and keep the store's
local fetch state with exponential back-off and Retry-After.

DeviceSync::run_podcast_action hands PodcastStore actions stamps reserved
in the device-sync log and appends the operations they return with exactly
those stamps. Podcast operations stay out of outgoing sync batches until
this client speaks sync protocol v4.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 19:54:48 +02:00
sanapachandClaude Opus 5.5 bc04587252 Bump music-dht to 0.6.0 and furumi-library to 0.3.0
TrackItem gained a podcast field; music literals set it to None. The
music-dht podcast-feed feature provides the shared RSS/Atom parser.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 19:37:28 +02:00
sanapachandClaude Opus 5.5 595c886303 Show both keymap notice and logging warning at startup
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 15:26:30 +02:00
sanapachandClaude Opus 5.5 78bf2cf583 Keep all tabs visible on narrow terminals and wrap the podcasts placeholder
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 15:26:30 +02:00
sanapachandClaude Opus 5.5 df7ad3c8b7 Reject a keymap version nested in a binding; fix macOS keymap path in docs
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 15:26:30 +02:00
sanapachandClaude Opus 5.5 df171208eb Document the new tab order and keymap version
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 15:18:00 +02:00
sanapachandClaude Opus 5.5 e78f1627da Reorder tabs and migrate legacy keymap tab indices
Tabs are now 1 Library, 2 Playlists, 3 Queue, 4 Podcasts, 5 Settings,
6 Logs. The Podcasts tab is a placeholder that states podcasts are not
available in this build yet; it gets its own "podcasts" key context.

Keymap files gain an optional top-level `version`. The default keymap
declares `version = 2` and binds "6" to the Logs tab. Files without a
version (or with version 1) have their GoToTab indices remapped in
memory (3 -> 4, 4 -> 5, and 5 -> 3 for the prototype podcast build) with
a startup notice; the user's file is never rewritten. The help window
names the target tab instead of "Go to tab N".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 15:17:59 +02:00
Aleksandr Bogomiakov 292f17fee1 Added MODE status 2026-11-18 16:18:56 +00:00
Aleksandr Bogomiakov 3e46f21804 Fixed artist card fed update 2026-11-18 15:43:43 +00:00
Aleksandr Bogomiakov 7f0ca2984f Fixed artist card fed update 2026-11-18 15:41:54 +00:00
Aleksandr Bogomiakov 0ad3844d37 Bump 2026-11-16 00:17:50 +00:00
Aleksandr Bogomiakov 2253ec7d91 Added simple status visual 2026-11-15 23:48:33 +00:00
Aleksandr Bogomiakov 8dd3ededf6 Fixed queue bug 2026-10-10 00:19:10 +01:00
Aleksandr Bogomiakov 81fdcf13ae Fixed queue bug 2026-10-10 00:18:07 +01:00
Aleksandr Bogomiakov a6d502e319 Fix duplicate queue playback position 2026-10-09 23:54:07 +01:00
Aleksandr Bogomiakov 3298204f2e Bump lock 2026-10-09 15:42:17 +01:00
Aleksandr Bogomiakov 9155bb9e00 Fixed release fed search regression 2026-10-09 15:34:20 +01:00
ab b07bcd4ddd Added fix 2026-09-10 22:56:06 +03:00
ab 966cf4b437 Fix connected devices 2026-09-10 18:05:00 +03:00
ab 532d6ee1e9 Integrate shared playback coordination and release 0.3.1 2026-09-10 17:07:41 +03:00
ab 5a193d839f Reworked settings menu 2026-09-07 13:06:46 +03:00
ab 7d6af59e97 fix lock 2026-09-07 12:41:27 +03:00
ab 32c976beb8 Added self updater 2026-09-07 12:36:48 +03:00
Ultradesu 2607314da3 Fix lock 2026-09-02 15:50:41 +01:00
Ultradesu f901836929 fix federation recovery after sleep 2026-09-02 15:10:20 +01:00
Ultradesu 0c30cdfcc6 Added ogg opus support 2026-08-14 11:42:54 +01:00
Ultradesu cfc0bfa0e5 Moved library to FRID 2026-08-11 18:13:02 +01:00
Aleksandr Bogomiakov 079d87a831 Merge local and federated similarity results 2026-08-10 20:51:21 +01:00
Aleksandr Bogomiakov add764e51d Stabilize similarity and library status cards 2026-08-10 20:18:51 +01:00
Aleksandr Bogomiakov 87cb7fe74c Route similarity search through the DHT 2026-08-10 19:40:37 +01:00
Aleksandr Bogomiakov e95d2e7fe1 Added similarity search feature 2026-08-10 00:37:50 +01:00
Aleksandr Bogomiakov 03f74cc91e Add federated music similarity search 2026-08-10 00:22:20 +01:00
Aleksandr Bogomiakov c971e81eed Many UI changes 2026-08-02 03:04:16 +01:00
Aleksandr Bogomiakov f73e3e7b95 Added nix files. revorked queue append, added library migration. 2026-08-02 00:40:50 +01:00
Ultradesu cced546cd5 Fixed invite logic to be lightweight 2026-07-29 14:24:22 +01:00
Ultradesu 52c2f7f7fe Fixed invite logic to be lightweight 2026-07-29 14:21:01 +01:00
Ultradesu 9b9f5d9ce5 Global is default mode 2026-07-29 10:52:57 +01:00
Ultradesu 1f9539ffd7 Bump protocols. Added proto status 2026-07-28 22:59:35 +01:00
Ultradesu d854a4d4e0 Bump furumi 0.2.2 -> 0.2.3 2026-07-28 22:45:50 +01:00
Ultradesu 6175423b0c Bump protocols. Added proto status 2026-07-28 22:24:17 +01:00
Ultradesu 93dc8f02fb Bump protocols. Added proto status 2026-07-28 22:19:01 +01:00
Ultradesu 89c78dcadc Bump protocols. Added proto status 2026-07-28 22:18:29 +01:00
Ultradesu 34153cca9d Added jam 2026-07-28 18:58:38 +01:00
Ultradesu d4c219837b Added JAM feature 2026-07-28 18:41:08 +01:00
Ultradesu 1c721b68f5 Added JAM feature 2026-07-28 18:35:59 +01:00
Ultradesu 29466d70e8 Added --help 2026-07-28 11:18:14 +01:00
Ultradesu abf9ad782c Added --status to get simple status 2026-07-28 11:16:38 +01:00
Ultradesu 28189bae95 Added playback history window 2026-07-27 23:37:46 +01:00
Ultradesu a7f41ff205 Bump libs 2026-07-27 23:20:21 +01:00
Ultradesu 40c318a1d0 Update frid dependency for listening history 2026-07-27 23:19:45 +01:00
Ultradesu 0d6c89761f Sync listening history across devices 2026-07-27 23:15:57 +01:00
Ultradesu f55571ab34 Fixed status icon background 2026-07-27 17:38:14 +01:00
Ultradesu eb97c6469e Fixed liked track sorting 2026-07-27 17:16:39 +01:00
Ultradesu 7ebf07161e Fixed liked track sorting 2026-07-27 17:09:33 +01:00
Ultradesu d36f55b3f6 Reworked MODE switch 2026-07-27 14:13:56 +01:00
Ultradesu 5722e5aae6 prepared release 2026-07-26 03:51:36 +03:00
Ultradesu 4e1c52c4e6 fix readmi 2026-07-26 03:41:43 +03:00
Ultradesu d64deded3a Updated CI for brew 2026-07-26 03:16:42 +03:00
Ultradesu 864e84b159 Updated pic 2026-07-26 02:51:40 +03:00
Ultradesu 9aefaa364e Updated readme 2026-07-26 02:41:08 +03:00
Ultradesu c069ed9135 Updated readme 2026-07-26 02:21:16 +03:00
Ultradesu 3556120e10 Updated readme 2026-07-26 02:07:07 +03:00
Ultradesu ada18a4583 Reworked statistics 2026-07-26 01:41:16 +03:00
Ultradesu 17eb6a4fee Reworked statistics 2026-07-26 00:45:53 +03:00
Ultradesu 76f67372a1 Improved fiters. reworked Trak wrapper. 2026-07-25 23:57:19 +03:00
Ultradesu f80e10e6ad Improved fiters. reworked Trak wrapper. 2026-07-25 23:57:03 +03:00
Ultradesu c45f2e700b Reworked library. Added local, my, fed traks overview. 2026-07-25 23:24:49 +03:00
Ultradesu 788bc2e01f Added network catalog slices 2026-07-25 22:40:27 +03:00
ab b725ca8d05 Fixed status window 2026-07-25 02:10:20 +03:00
Ultradesu 38e3eb5a12 Added streaming. Improved UI 2026-07-25 01:23:29 +03:00
Ultradesu a516887830 Connected Devices: restyle status 2026-07-24 14:43:15 +03:00
Ultradesu 888038931a Connected Devices: added remote control 2026-07-24 05:42:16 +03:00
Ultradesu 3d3fd20b57 Connected Devices: added remote control 2026-07-24 05:31:29 +03:00
Ultradesu 33fa2346f0 Connected Devices: added remote control 2026-07-24 05:19:28 +03:00
Ultradesu d62c79b50c Connected Devices: added remote control 2026-07-24 05:09:33 +03:00
Ultradesu 8605c72f10 Connected Devices: added remote control 2026-07-24 04:56:26 +03:00
Ultradesu b14781f5a4 Connected Devices: added remote control 2026-07-24 04:49:48 +03:00
Ultradesu 389eacd388 Connected Devices: added remote control 2026-07-24 04:33:50 +03:00
Ultradesu 1065ea5afc Connected Devices: added remote control 2026-07-24 04:20:52 +03:00
Ultradesu 9352b493a1 Connected Devices: added remote control 2026-07-24 04:11:01 +03:00
Ultradesu a737456daf Connected Devices: fixed rplaylist sync 2026-07-24 03:35:42 +03:00
Ultradesu be58933e8d Connected Devices: fixed rplaylist sync 2026-07-24 03:22:18 +03:00
Ultradesu e83f356005 Connected Devices: fixed rplaylist sync 2026-07-24 03:11:33 +03:00
Ultradesu 682794755e Connected Devices: fixed rplaylist sync 2026-07-24 03:06:20 +03:00
Ultradesu 71d31505f9 Connected Devices: fixed rplaylist sync 2026-07-24 02:35:36 +03:00
Ultradesu e08eb71ab7 Connected Devices: fixed UI settings. fixed pairing protocol 2026-07-24 02:21:24 +03:00
Ultradesu fa58b2ce43 Connected Devices: fixed UI settings. fixed revocation 2026-07-24 01:43:56 +03:00
Ultradesu cc3153cc3a Connected Devices: fix stream finish 2026-07-24 01:31:16 +03:00
Ultradesu f85c806b43 Connected Devices: fix stream finish 2026-07-24 01:24:18 +03:00
Ultradesu b47c271ec0 Connected Devices: fix stream finish 2026-07-24 01:18:02 +03:00
Ultradesu adbb76b031 Connected Devices: Added sync feature 2026-07-24 00:54:27 +03:00
Ultradesu 7fe6ddfe05 Added filter. Improved UI. Fixed settings window 2026-07-23 19:43:47 +03:00
Ultradesu 6dbfc83bf6 Fixed imports 2026-07-23 18:54:57 +03:00
Ultradesu 5e346bf535 Added Visualisation engine on rhai 2026-07-23 18:51:32 +03:00
Ultradesu 32a038dba6 Added Visualisation engine on rhai 2026-07-23 18:48:58 +03:00
Ultradesu af2542b668 Improved UI. 2026-07-23 17:35:11 +03:00
Ultradesu 5d54894437 Sync with FRID protocol v5. Improved direct content id search 2026-07-23 16:45:30 +03:00
Ultradesu 2128cd2300 Fixed artist page sorting 2026-07-23 14:23:22 +03:00
Ultradesu 0b2eaa1496 fixed frid 2026-07-21 20:12:31 +03:00
Ultradesu 6c808aea5c Extendex DHT info 2026-07-21 20:10:37 +03:00
Ultradesu da5d2410ac fed fixes 2026-07-21 00:12:45 +03:00
Ultradesu 151e2cf337 Many UI fixes 2026-07-17 15:29:10 +03:00
Ultradesu 70261a3bf4 fixed translate 2026-07-17 01:48:41 +03:00
Ultradesu ff97053156 Improved fed artist page 2026-07-17 01:43:09 +03:00
Ultradesu a723fcc18e Added fed artist page 2026-07-17 01:17:54 +03:00
Ultradesu 73ee4dab9d Fixed track art 2026-07-17 00:00:34 +03:00
Ultradesu eb8ed966f1 fixed art sync 2026-07-16 21:23:01 +03:00
Ultradesu b027db8a09 fixed metadata import 2026-07-16 21:16:15 +03:00
Ultradesu 691abe599b fixed search result nav 2026-07-16 20:49:53 +03:00
Ultradesu 3df41cfc3b fixed build via git 2026-07-16 20:33:42 +03:00
Ultradesu b1f8f4cb01 init federation 2026-07-16 20:29:51 +03:00
Ultradesu 98525718d0 Improved auth stability 2026-06-17 10:34:03 +01:00
Ultradesu cf82b203a9 Improved auth stability 2026-06-16 22:34:01 +01:00
Ultradesu 2da81ecb89 Improved auth stability 2026-06-16 03:55:11 +01:00
Ultradesu 54ba8b4309 Fixed lock 2026-06-15 12:37:27 +01:00
100 changed files with 59345 additions and 5905 deletions

No files matched your search

+13 -3
View File
@@ -10,6 +10,7 @@ permissions:
env:
CARGO_TERM_COLOR: always
CARGO_NET_RETRY: 10
jobs:
build:
@@ -24,7 +25,7 @@ jobs:
archive_ext: tar.gz
binary_name: furumi
- os: macos-latest
asset_name: furumi-macos-x86_64
asset_name: furumi-macos-aarch64
archive_ext: tar.gz
binary_name: furumi
- os: windows-latest
@@ -43,8 +44,11 @@ jobs:
- name: Show Rust version
run: rustc --version && cargo --version
- name: Fetch locked dependencies
run: cargo fetch --locked
- name: Build
run: cargo build --release --locked
run: cargo build --release --locked --offline
- name: Package
shell: bash
@@ -57,6 +61,7 @@ jobs:
mkdir -p "$package_dir"
cp "target/release/${{ matrix.binary_name }}" "$package_dir/"
cp README.md "$package_dir/"
cp LICENSE "$package_dir/"
if [[ "${{ runner.os }}" == "Windows" ]]; then
(cd dist && 7z a "../${archive_name}" "${{ matrix.asset_name }}")
@@ -93,7 +98,12 @@ jobs:
run: |
set -euo pipefail
gh release create "$RELEASE_TAG" artifacts/*/* \
# Hash archive bytes; manifest entries use the release asset basenames.
for archive in artifacts/*/*; do
(cd "$(dirname "$archive")" && sha256sum "$(basename "$archive")")
done > SHA256SUMS
gh release create "$RELEASE_TAG" artifacts/*/* SHA256SUMS \
--title "furumi ${RELEASE_TAG}" \
--notes "Release ${RELEASE_TAG}" \
--verify-tag
+288
View File
@@ -0,0 +1,288 @@
# AGENTS.md
This file describes how to work safely in the Furumi repository. It applies to
the entire project.
## Project intent
Furumi is a cross-platform, federated P2P player for personal music libraries.
Every node must remain a complete local player without network access. Other
nodes add discovery, availability, trusted-device synchronization, and direct
track transfer; they are never a prerequisite for using the local library.
Read `ARCHITECTURE.md` before changing federation, device sync, playback
handoff, persistence, or runtime boundaries.
Preserve these architectural invariants:
1. Local import, browsing, playback, playlists, likes, and history work
offline.
2. No central Furumi service becomes required for discovery, playback, or
synchronization.
3. Federation membership does not imply trusted-device membership.
4. Remote state is merged, replicated, or cached locally; it is not treated as
an always-available database.
5. Network, database, filesystem, image, and audio preparation work stays out
of the interactive UI path.
6. Losing peers may reduce remote availability but must not invalidate local
state.
## Toolchain and checks
The crate uses Rust edition 2024 and Rust 1.97 or newer.
Run the checks relevant to every code change:
```bash
cargo fmt --all -- --check
cargo check --all-targets
cargo test --all-targets
cargo clippy --all-targets
```
`cargo clippy --all-targets` currently reports known warnings. Do not hide
them with broad `allow` attributes. Do not claim `-D warnings` passes unless
the existing warning set has actually been resolved.
Use `cargo fmt --all` after editing Rust. Keep `Cargo.lock` committed and
update it only when dependencies change.
## Source boundaries
- `src/main.rs` owns process startup, terminal restoration, Tokio setup, and
platform media-loop integration.
- `src/app/state.rs` owns UI/navigation state.
- `src/app/action.rs` and `src/app/event.rs` define input intent and runtime
results.
- `src/app/update.rs` performs state transitions and requests effects. It must
not perform blocking I/O.
- `src/app/mod.rs` owns runtime orchestration and effect execution.
- `src/library/` owns SQLite library queries, models, imports, and migrations.
- `src/player/` owns rodio playback and audio analysis.
- `src/federation/` owns DHT discovery, peer catalogs, audio exchange, and
federation caches.
- `src/podcasts/` owns podcast feed HTTP and refresh policy, the episode
stream reader (HTTP Range, bounded buffer) and the ordered progress writer;
podcast identity, merge rules and the SQLite store come from FRID
(`music_dht::podcast`, `furumi_library::podcasts`) and must not be
re-derived here. Public podcast cards are published only through
`podcasts::publication` (`PodcastDht::sync_shares` over the merged
registers): never publish a podcast directly, never log feed URLs or ids of
podcasts that are not shared, never put progress, history, counters or
device names into a card. A local share-off or unsubscribe asks for an
immediate pass (`Reconciler::revoke_now`), which quitting waits for, and
privacy confirmations change only through `publication::set_shared` /
`ShareConfirmations` (bound to the share decision, never synced). Nothing
is published before `DeviceSync::podcast_registers_current` (a restarted
device may hold a revoked share decision); passes before it only revoke.
Public cards found by search are publisher claims:
subscribe and preview only through `podcasts::discovery`, which uses the
card's origin URL (`PodcastSearchHit::feed_url`), never a claimed URL, and
never stores card metadata. Queue items are identified by `state::track_key`
/ `TrackItem::key`, never by numeric id (every episode has the same sentinel
id); music-only code must skip `TrackItem::is_podcast()` items.
- `src/devices.rs` owns trusted-device replication, membership, and playback
coordination. Its wire types are the shared `music_dht::device_sync`
definitions; do not add local copies (golden tests in
`devices/wire_compat_tests.rs` keep the v3 JSON).
- `src/ui/` renders `AppState`; rendering code must not start background work
or mutate persistence.
- `src/media.rs` owns OS media controls.
- `src/visualizer.rs` and `src/visualizations/` own the Rhai visualization
host and bundled scripts.
Prefer adding a focused module when a responsibility has a clear boundary.
Do not split files solely to reduce line count if doing so introduces leaky
APIs or circular ownership.
Keep large test suites in their existing adjacent files:
- `src/app/update_tests.rs`
- `src/devices/tests.rs`
- `src/federation/tests.rs`
- `src/library/tests.rs`
## Application state and concurrency
`AppState` is the single source of truth for the TUI. The normal flow is:
```text
external event -> AppEvent -> Action/update -> Effect -> runtime -> AppEvent
```
Follow these rules:
- Keep update logic deterministic wherever practical.
- Return an `Effect` for work that requires runtime services.
- Report asynchronous results through `AppEvent`.
- Use `tokio::task::spawn_blocking` for blocking SQLite, hashing, tag parsing,
or filesystem-heavy work invoked from async code.
- Do not hold a mutex guard across `.await`.
- Do not call terminal rendering APIs from background tasks.
- Preserve event sequence or request identifiers where they prevent stale
search, download, or synchronization results from overwriting newer state.
## Library and SQLite
`library::Library` is the authority for local catalog persistence. Keep SQL in
the library/device persistence layers rather than spreading it through the UI
or runtime.
When changing schema or stored data:
- provide an upgrade path for existing databases;
- make migrations repeatable and safe on partially upgraded databases;
- preserve foreign-key and uniqueness invariants;
- distinguish durable user data from replaceable federation/cache data;
- test both the new behavior and migration-sensitive queries;
- never solve a schema problem by deleting or recreating a user's database.
Content identifiers are the bridge between independent libraries. Avoid
assuming that local numeric row IDs identify the same track on another node.
## Federation and wire protocols
Discovery and transfer are separate concerns:
- the DHT provides distributed discovery;
- peer catalog streams provide richer metadata;
- audio streams transfer content;
- the device-sync protocol replicates trusted personal state.
Treat protocol and serialized-data changes as compatibility changes:
- preserve existing ALPN values unless intentionally introducing a new
protocol version;
- retain backward-compatible `serde` defaults for fields added to wire types;
- tolerate peers with older or partial metadata;
- bound incoming messages and validate untrusted lengths/identifiers;
- keep catalog/federation authority separate from trusted-device authority;
- assume peers can disappear between discovery and transfer;
- keep retries and fallback sources idempotent.
Do not introduce a required coordinator, registry, account server, or canonical
network database.
## Trusted-device synchronization
Device sync is offline-first. Operations may arrive late, more than once, or
in a different order.
When changing it:
- preserve operation-ID deduplication;
- use the existing hybrid logical time ordering rules consistently;
- ensure deletes survive offline replicas through tombstones;
- compact tombstones only after the required acknowledgements;
- keep snapshots able to repair peers that missed older operations;
- treat membership and revocation as replicated durable state;
- keep playback commands targeted and deduplicated;
- test merge behavior from at least two operation orders;
- never store this build's protocol version for another device: use the
device's own report (`profile_protocol_version`) and only raise a stored
version from relayed profiles (`relayed_protocol_version`);
- gate everything a peer cannot parse by the version it reported: podcast
operations, podcast snapshot sections and playback state with podcast items
go only to v4 peers (`op_allowed_for_peer`, `SyncSnapshot::for_peer`,
`playback_allowed_for_peer`), a podcast queue is never handed to an older
device and its playback commands are ignored while the queue has episodes;
never strip episodes from a queue to make it fit an old peer; an older
peer still gets the playback coordination, with the queue redacted
(`redact_for_jam`), so its engine does not fail over, and the
"Private item" music entries it echoes back in its own states are left
out (`drop_echoed_private_items`), never adopted;
- apply podcast operations and snapshot sections only through
`PodcastStore` (`apply_remote_op`, `apply_snapshot`); never call the
podcast store while holding the sync-log connection;
- keep Jam snapshots redacted (`redact_for_jam`) and map guest placeholders
back with `restore_jam_private_items`.
Do not replace eventual reconciliation with assumptions about a continuously
connected leader.
## Playback and remote resolution
The application owns the logical queue; `player::Controller` owns physical
audio playback.
Remote and local tracks should continue through the same queue and UI model.
When a track is unavailable locally, resolve it asynchronously and replace or
materialize the pending entry without blocking the event loop.
Preserve:
- queue position and prefetch indexes when inserting or removing tracks;
- shuffle/repeat behavior;
- pause and seek state during device handoff;
- fallback to another advertised source when a peer disappears;
- the distinction between cached audio and content imported into the durable
library.
## UI and key bindings
The TUI is keyboard-first and cross-platform.
- Keep rendering pure over `&AppState`.
- Use semantic `Action` values rather than checking raw keys inside views.
- Add default bindings in `src/config/default_keymap.toml`.
- Preserve user overrides and context-specific bindings.
- Tabs are ordered Library, Playlists, Queue, Podcasts, Settings, Logs
(`1`–`6`). `Tab::ALL` defines that order for the tab bar, Tab/Shift+Tab,
and `GoToTab` indices. Changing it, or the meaning of any other
positional action argument, requires a new `KEYMAP_VERSION` and an
in-memory migration of older keymap files; never rewrite the user's file.
- Account for narrow terminals, Unicode display width, and empty/loading/error
states.
- Restore raw mode, alternate screen, bracketed paste, and keyboard
enhancements on exit and panic.
Do not print to stdout/stderr while the alternate-screen UI is active; use
`tracing` and visible application status instead.
## Cross-platform work
Furumi supports Linux, macOS, and Windows.
- Keep OS-specific code behind narrow `cfg` boundaries.
- Do not introduce shell-only behavior into portable paths.
- Use platform data/config/cache directories through the existing config
helpers.
- Consider path encoding, separators, and non-UTF-8 filesystem values.
- Changes to media controls, terminal setup, clipboard behavior, or audio
devices require explicit review of all three platforms.
If only one target can be exercised locally, state which platform-specific
paths remain unverified.
## Tests
Add tests at the closest stable boundary:
- pure state transitions in `app/update_tests.rs`;
- SQLite behavior and migrations in `library/tests.rs`;
- operation merge, tombstone, membership, and playback sync behavior in
`devices/tests.rs`; podcast sync between device stores and simulated v3
peers in `devices/podcast_sync_tests.rs`; wire shapes in
`devices/wire_compat_tests.rs`;
- search/ranking/federation conversion in `federation/tests.rs`;
- protocol-specific tests beside `federation/audio.rs` or
`federation/catalog.rs` when appropriate.
Prefer in-memory SQLite databases and deterministic fixtures. Temporary files
must use unique names and must not depend on a developer's music library,
configuration, home directory, network peers, or audio hardware.
Do not remove a test merely because a refactor makes it inconvenient. Update
it to assert the preserved behavior.
## Documentation and releases
Keep public documentation aligned with the decentralized product model.
README content should explain user value and setup; `ARCHITECTURE.md` should
explain architectural decisions and invariants rather than restating source
code.
Release archives are produced by `.github/workflows/release.yml` and must
include the binary, `README.md`, and `LICENSE`.
The project is licensed under WTFPL version 2.
+630 -202
View File
@@ -1,240 +1,668 @@
# furumi_cli — Architecture
# Furumi architecture
Cross-platform terminal client (cmus-style TUI) for the furumusic backend.
Targets: macOS, Linux (ALSA/Pulse/PipeWire), Windows (WASAPI, Windows Terminal).
Furumi is an autonomous music player that can cooperate with other Furumi
players. The architecture starts from one constraint: **a node must remain a
complete and useful player when every other node is unavailable**.
## 1. Technology choices
Networking therefore extends a local player instead of becoming a prerequisite
for it. There is no control plane, account service, canonical catalog, or
server-owned source of truth.
### TUI: ratatui 0.30 + crossterm 0.29
## Architectural goals
Evaluated: **ratatui**, cursive, tui-realm, iocraft.
The design optimizes for five properties:
- **ratatui 0.30.x** — the de-facto standard (gitui, yazi, spotify-player all use it).
0.30 split the project into workspace crates (`ratatui-core`, `ratatui-widgets`,
`ratatui-crossterm`) with a stable core API. Stock widgets cover everything we
need: `Tabs`, `List`, `Table`, nested `Layout` for tile grids.
- cursive — maintenance mode since 2024, rejected.
- tui-realm — viable framework on top of ratatui (termusic uses it), but a
single-maintainer abstraction layer; we prefer plain ratatui with our own
thin component layer.
- iocraft — too young, optimized for inline CLI output rather than fullscreen apps.
- termion — Unix-only, eliminated (we need Windows).
1. **Local autonomy** — importing, browsing, playback, playlists, likes, and
history work entirely on one device.
2. **No central failure domain** — discovery, catalog exchange, streaming, and
synchronization do not depend on a Furumi-operated service.
3. **Offline tolerance** — trusted devices may change state independently and
reconcile after reconnecting.
4. **Incremental federation** — one node is complete; every additional node
increases availability and the amount of discoverable music.
5. **Explicit trust boundaries** — personal-device replication and wider
music federation are different protocols with different authority.
crossterm is the only backend that covers Windows. Caveats to handle:
- Enable kitty keyboard enhancement flags only when
`supports_keyboard_enhancement()` returns true; always pop flags on exit.
- Filter key events to `KeyEventKind::Press` (Windows and kitty-enhanced
terminals also deliver Repeat/Release — otherwise bindings double-fire).
- Restore the terminal on panic (panic hook) — a TUI that corrupts the shell
is the #1 reliability complaint.
These goals are more important than maintaining a globally identical view of
the network. Furumi prefers useful local progress and eventual reconciliation
over distributed consensus.
### Keybindings: crokey + TOML keymap
## The node model
- **crokey 1.4** — parses/formats key combos (`ctrl-a`, `g`), serde support, used
for the config file format.
- Keymap model copied from spotify-player: a `[[keymaps]]` TOML table mapping a
*key sequence* (space-separated chords, e.g. `"g g"`, `"C-c x"`) to a
`Command` enum, optionally parameterized (`{ SeekForward = { seconds = 10 } }`).
- A small chord state machine resolves sequences; bindings are layered:
built-in defaults ← user config (`~/.config/furumi/keymap.toml`).
- Bindings resolve per *input context* (Global, LibraryGrid, TrackList,
TextInput, Popup) so the same key can mean different things per view.
Every running Furumi instance contains the same four capabilities:
### Audio: rodio 0.22 + stream-download, behind a backend trait
Evaluated: **rodio**, kira, raw cpal+symphonia, gstreamer-rs, libmpv.
- **rodio 0.22** (`Player` / `DeviceSinkBuilder` API — note the 0.21/0.22 renames;
most older tutorials are outdated). Symphonia is the default decoder; enable
the `aac`, `isomp4`, `alac` features for m4a support. Pure Rust → trivial
cross-compilation; cpal covers CoreAudio / ALSA / WASAPI.
- **stream-download 0.24** bridges HTTP to rodio: background download exposing
blocking `Read + Seek`, built on reqwest (shares our authenticated client,
auth headers included), seek into undownloaded regions via HTTP Range
(the backend's `/stream/{id}` supports Range), temp-file storage, retries.
- kira — game-audio oriented, no network story, rejected.
- gstreamer / libmpv — best playback quality but heavy system dependencies;
not acceptable as the only backend for a portable CLI.
Playback lives behind a trait so backends can be added later (termusic ships
rodio + mpv + gstreamer this way):
```rust
trait AudioBackend {
fn play(&mut self, source: TrackSource) -> Result<()>;
fn pause(&mut self); fn resume(&mut self);
fn seek(&mut self, pos: Duration) -> Result<()>;
fn set_volume(&mut self, v: f32);
fn position(&self) -> Duration;
fn events(&self) -> Receiver<PlayerEvent>; // TrackEnded, Failed, ...
}
```text
┌─────────────────────────────────────────────────────────┐
│ Furumi node │
│ │
│ Local library ── Playback engine ── TUI / media keys │
│ │ │ │
│ ├── Trusted-device replication │
│ │ │
│ └── Federation: discovery, catalog, audio │
└─────────────────────────────────────────────────────────┘
```
Gapless-ish playback: pre-open the `stream-download` source and decoder for the
next queue item and append it to the rodio `Player` before the current track
ends. (True gapless is impossible for AAC/M4A anyway — symphonia has no AAC
gapless trim.)
The local SQLite library is authoritative for that node. Network data is
merged into local views or materialized as pending remote content; it does not
replace the local database with a remote database abstraction.
### Async runtime: tokio
This keeps the core behavior predictable:
Needed for: crossterm `EventStream`, reqwest, stream-download, device-sync
polling, debounced search. The audio decode thread is rodio's own; everything
else is async tasks talking over channels.
- disconnecting never makes the local collection unavailable;
- downloaded content can become ordinary local content;
- a peer disappearing reduces availability but does not invalidate local
state;
- nodes may join and leave without electing a leader.
## 2. Application architecture
## Two network layers
Elm-style (TEA) core with a component-per-view UI layer — the pattern from the
official ratatui component template and spotify-player.
Furumi deliberately separates **trusted-device synchronization** from
**federated music exchange**.
```
┌────────────────────────────────────────────┐
│ main loop │
│ recv Event -> keymap -> Action -> update() │
│ tick -> draw(&state) │
└───────▲──────────────────────────┬──────────┘
Event (mpsc) │ │ Command (spawn task / send msg)
┌─────────────────────┼──────────────┐ │
│ terminal input (crossterm stream) │ ┌───────▼────────┐
│ api task results │ │ side effects │
│ player events (TrackEnded, ...) │ │ api::Client │
│ device-sync poll results/commands │ │ player::Engine │
│ tick (render + position updates) │ │ sync::Poller │
└────────────────────────────────────┘ └────────────────┘
### Trusted-device synchronization
This layer connects devices owned or trusted by the same user. It carries
personal state such as:
- likes and playlist operations;
- podcast subscriptions, episode progress and listening sessions;
- device membership and revocation;
- acknowledgements and synchronization progress;
- playback state, commands, and handoff information.
Pairing establishes the trust relationship. After that, changes are replicated
through an append-only operation log and applied to materialized local tables.
The wire types are the shared `music_dht::device_sync` definitions (protocol
v4); golden tests keep the v3 JSON of furumi-tui 0.3.x byte for byte.
Each device stores the protocol version that the other devices report
themselves (their hello and pairing profiles, the sender's own entry of a
`devices` list, their own profile announcements). A relayed profile only
raises a stored version, because older relays list every device with their
own constant; this build never stores its own version for another device.
Everything a peer cannot parse is gated by that version: podcast operations,
podcast snapshot sections and playback state that contains podcast items
reach only v4 peers (`op_allowed_for_peer`, `SyncSnapshot::for_peer`,
`playback_allowed_for_peer`). An older client would reject a whole message
over one unknown operation kind, or silently drop an episode it does not
understand.
### Music federation
Federation connects independent libraries. It provides:
- decentralized discovery through the DHT;
- automatic publication of searchable local catalog metadata;
- richer artist and release catalogs fetched from peers;
- direct audio transfer when a selected track is not available locally.
Federation does not grant another peer authority over personal playlists,
likes, or device membership. A node may participate in federation without
joining another user's trusted-device group.
Keeping these layers separate prevents discovery convenience from silently
becoming a synchronization trust decision.
### Federation Jam control
Jam is a third, deliberately narrow authority boundary. A host creates an
opaque `frid://j/...` runtime capability and remains the only node producing
audio. Other TUI peers use a dedicated Jam ALPN to submit the same portable
playback commands used by connected-device control and receive the host's
playback snapshot. They receive queue metadata, not audio.
Jam never exchanges trusted membership, likes, playlists, listening history
or podcast state. The host's podcast episodes are private: the published
snapshot replaces them with opaque placeholders (`redact_for_jam`), guest
commands that add episodes are dropped, and a guest's placeholders are mapped
back to the host's episodes (`restore_jam_private_items`); a change that
drops, duplicates or seeks in them is refused. Volume remains local. Commands carry unique IDs and are retried until
the host acknowledges them, while inactive participants expire from the
runtime session. Regenerating the capability or restarting the host invalidates
the previous link.
## Discovery and direct communication
Furumi separates finding content from transferring it.
```text
discovery plane
Local catalog ───────> DHT <─────── Other catalogs
│
│ peer + content identity
v
direct P2P connection
├── catalog protocol
├── audio protocol
└── device-sync protocol
```
Key rules:
The DHT is the distributed index. Nodes publish compact searchable
descriptions of their local library and query the network without contacting a
central search service.
- **Single source of truth**: one `AppState` struct, mutated only in `update()`.
Views are pure render functions over `&AppState`.
- **No blocking in the UI loop.** All I/O (HTTP, audio open) happens in spawned
tasks that report back via the event channel. Every remote list is a
`Loadable<T> { NotAsked, Loading, Loaded(T), Failed(Error) }` so views can
render spinners and errors honestly.
- **Input → Action indirection**: raw key events are translated by the keymap
into semantic `Action`s (`PlayPause`, `FocusNextTab`, `Select`, `Back`,
`SeekForward(10)`). Views never see raw keys; this is what makes bindings
configurable and the app testable.
Opening a local artist or release card in a network-enabled library view
enriches it asynchronously. DHT matches identify likely catalog owners, while
a bounded set of known peers can also answer directly when the index is
incomplete. Card results are replaceable snapshots: reopening a card or
periodic maintenance retries discovery, with at most one request per card in
flight. A failed refresh keeps the last usable snapshot, and never prevents
browsing the local tracks.
### Module layout (single crate now, splittable later)
Similarity discovery uses a separate schema-independent DHT overlay. A node
derives a deterministic 256-bit routing signature from every local embedding,
groups them into fixed two-level LSH buckets, and publishes compact summaries
containing only fine-bucket representatives, its peer identity, and the ticket
needed to dial a previously unknown owner. The owner signs every summary with
its existing transport key, so storage peers can relay and cache it but cannot
impersonate or modify it. Summaries expire with the ordinary library-record TTL
and are replaceable federation cache, never local library authority.
```
src/
main.rs // setup: terminal guard, tokio, channels, run loop
config/ // Config + keymap loading (figment or manual TOML merge)
api/ // typed client for /api/player/*
client.rs // reqwest wrapper: base_url, bearer auth, retries
auth.rs // password login, token store, auto-refresh (15min TTL)
models.rs // ArtistCard, Release, TrackItem, PlaylistCard, ...
player/ // playback engine
backend.rs // AudioBackend trait
rodio_backend.rs // rodio Player + stream-download sources
queue.rs // queue, shuffle, repeat_mode, next-track prefetch
sync/ // connected devices: heartbeat/poll loop, command handling
app/ // AppState, Action, Event, update()
ui/ // ratatui rendering
views/ // library_grid, artist, release, playlists, search,
// queue, devices, now_playing bar, popups
theme.rs
A similarity search first performs bounded multi-probe LSH lookups to rank
likely owners, then sends the existing normalized-vector request directly to
at most 16 peers initially and 48 on fallback. Known peers remain a rollout
fallback. The model, preprocessing, durable embeddings, exact cosine search,
and consent policy remain client-owned; `music-dht` owns only compatible
routing math, signed records, replication, and wire bounds.
Once a peer is known, communication moves to direct P2P streams provided by
iroh through `music-dht`. Furumi defines separate application protocols for
catalog requests, audio transfer, and trusted-device synchronization. This
keeps discovery traffic small and lets large or private exchanges happen only
between the participating peers.
Relay-assisted connectivity may help peers establish a route, but relays do
not become catalog authorities or application-state owners.
## Identity and content resolution
Network operations refer to content independently of any one library row.
Content identifiers allow a node to ask:
1. Is this track already present in my local library?
2. Does one of my trusted devices have it?
3. Which federation peers currently advertise it?
Resolution follows that order conceptually: prefer a ready local source, reuse
known content where possible, and fetch from a peer only when necessary.
A federated track can initially exist as a lightweight pending item in a queue
or playlist. When playback reaches it, Furumi resolves an available peer,
starts the transfer, and either uses the cache or imports the result into the
local library. The rest of the player continues to work with the same
`TrackItem` model, so local and remote availability do not require separate
playback systems.
## Offline-first synchronization
Trusted devices do not share a live database connection. Each device records
operations locally and exchanges them when connectivity returns.
The synchronization model combines:
- immutable operation identifiers for deduplication;
- hybrid logical timestamps for deterministic last-writer decisions;
- materialized tables for fast UI queries;
- tombstones so deletion survives offline replicas;
- per-peer acknowledgements to determine when old tombstones can be compacted;
- snapshots to repair a peer that missed older operations.
Vectors only grow, so operations hidden from a peer while it ran an older
protocol are never sent again after it upgrades. Snapshots are the recovery
path for that case; the podcast sections carry the subscription, share and
progress registers and the most recent listening sessions, bounded by the
shared FRID limits and by the line budget of each message.
This is eventual consistency scoped to a trusted device group. A temporarily
offline laptop can modify playlists, another device can continue playback, and
both can later converge without a permanently available coordinator.
Membership changes use the same replicated model. Revocation is state that
must propagate and converge, not an ephemeral server-side session flag.
## Playback across devices
A persisted device identity has exactly one live coordinator. The TUI holds
an OS file lock beside its device-sync database for the entire runtime; two
installations using the same user data directory cannot open it concurrently.
Network polling is independent per trusted peer, with one in-flight exchange
per peer and a bounded deadline. A stalled peer must not delay the next poll
of a healthy output. Poll tasks are cancelled when federation shuts down.
Playback has one logical state but remains physically local to the device
producing audio.
The synchronized state describes the queue, current item, position, pause
state, volume, shuffle/repeat mode, and the active playback owner. Commands are
targeted and deduplicated. Handoff transfers intent and position; the receiving
device resolves the track against its own library or federation sources before
starting its audio engine. Each queue item names its source: a podcast episode
travels as `PlaybackSource::PodcastEpisode` with the reference needed to play
it (the receiving device streams it from the publisher at the handed-off
position, with or without a subscription). A queue with episodes is not handed
to a device below protocol v4, and playback commands from such a device are
ignored while the local queue has episodes. Such a device still gets the
playback snapshot with its coordination envelope, but with every episode
replaced by an opaque "Private item" (`redact_for_jam`): an engine renews the
owner's liveness only from the owner's own announcements, so an old device
that heard nothing would take over by automatic failover after
`owner_timeout_ms` and replace the queue. This departs from FRID's
`PLAYBACK_PROTOCOL.md` rule 1 ("otherwise send `None`") and is reported to
FRID as a contract gap. An old device that mirrors such a queue drops the
`source` its types do not know, so each placeholder becomes a music item
titled "Private item"; when it later takes over (Play on it, a paused-startup
claim, failover while this device is gone) or sends a command, it announces
those. States from devices below v4 are therefore cleaned on receipt
(`drop_echoed_private_items`: bare music items with that title and no content
id, federated source, artist, release or duration), with a status message.
Active-device leases and idle timing prevent stale snapshots from immediately
taking control after a device reconnects. This provides practical coordination
without introducing a central playback arbiter.
## Local application architecture
Inside one node, Furumi uses an event-driven state machine:
```text
terminal / player / database / network / OS media events
│
v
AppEvent
│
input → Action
│
v
update(AppState)
│
optional Effect
│
v
asynchronous runtime work
│
└──────────> AppEvent
```
The `api`, `player`, and `app` layers do not import `ui` or ratatui. If a
shared core for furumi_macos/android ever makes sense, those modules extract
into workspace crates without surgery.
`AppState` is the single source of truth for the interface. The update layer
performs deterministic state transitions and requests effects; it does not
perform blocking I/O. SQLite access, imports, artwork decoding, DHT queries,
peer transfers, and audio preparation run through runtime services and report
their results as events.
## 3. UI model
This structure gives the TUI three important properties:
Persistent layout: a tab bar on top, the active view in the middle, a
now-playing/status bar at the bottom (track, position gauge, volume, shuffle/
repeat, active device indicator).
- rendering is a pure projection of current state;
- input behavior can be tested without starting audio or networking;
- slow peers and large imports cannot block terminal interaction.
Tabs (each owns a navigation stack, like a browser per tab):
The audio engine is similarly isolated. The application owns the logical
queue, while `player::Controller` owns rodio playback and receives explicit
commands. Prefetching prepares the next source before the current item ends.
1. **Library** — paginated grid of artist tiles (`GET /artists`).
`Enter` on a tile pushes **Artist view** (`GET /artists/{id}`: metadata,
top tracks, releases list). Selecting a release pushes **Release view**
(`GET /releases/{id}`: metadata + track list). `Esc`/`Backspace` pops.
2. **Search** — debounced `GET /search?q=` with artists/releases/tracks sections.
3. **Playlists** — own + saved playlists, likes ("Liked tracks" virtual playlist).
4. **Queue** — current play queue, reorder/remove.
5. **Devices** — connected devices list, pick active device, transfer playback.
### Versioned key bindings
Navigation state is `Vec<Route>` per tab; a `Route` is an enum
(`ArtistGrid { page }`, `Artist { id }`, `Release { id }`, ...). Views cache
their loaded data in `AppState` keyed by route so Back is instant.
Key bindings are semantic `Action` values loaded from the bundled defaults and
merged with the user's `keymap.toml`. Some actions carry positional meaning
(`GoToTab(index)` follows the displayed tab order), so changing the tab order
changes what an existing user file means. The keymap file therefore carries a
format `version`. Files from an older format are adapted in memory when they
are loaded and the user is told once per start; Furumi never rewrites a
user's configuration. The current format, version 2, orders tabs as Library,
Playlists, Queue, Podcasts, Settings, Logs; unversioned files use the earlier
order and have their tab indices remapped. A `version` key that TOML attached
to a binding (written after a `[[keymaps]]` header) is rejected, so a versioned
file is never silently mistaken for a legacy one.
Tile grid: computed from terminal width (`Layout` columns × rows), each tile a
bordered block with artist name (cover art rendering in-terminal is a later,
optional feature — e.g. ratatui-image with kitty/sixel detection, never a
hard dependency).
## Podcasts
## 4. Backend integration notes
Podcasts are a separate content type, not library tracks. The shared contract
lives in FRID: `music_dht::podcast` defines podcast and episode identity, feed
URL canonicalization, the RSS/Atom parser and the merge rules, and
`furumi_library::podcasts::PodcastStore` persists the catalog, the personal
registers (subscription, share, progress) and listening sessions in
`podcasts.sqlite3`. The TUI does not re-derive ids or merge rules.
(Verified against the furumusic source; base path `/api/player`.)
The TUI owns what the contract leaves to clients:
- **Auth**: `POST /api/auth/password` → access token (15 min) + refresh token
(60 days). Client stores tokens at `~/.config/furumi/credentials.json`
(0600) and refreshes proactively via `POST /api/auth/refresh`. All API calls
go through one client that retries once on 401 after refreshing.
- **Streaming**: `GET /api/player/stream/{track_id}` with `Accept-Ranges:
bytes` — exactly what stream-download needs for seek. Original files are
served untranscoded (mp3/flac/ogg/m4a/...), hence the symphonia feature set.
- **Playback state**: persisted server-side via `PUT /api/player/state`
(queue, position, shuffle, repeat, volume). We push throttled updates
(on track change + every ~10s while playing) and restore on startup.
- **History/scrobbling**: `POST /history` on track completion;
`POST /lastfm/now-playing` and `/lastfm/scrobble` if last.fm is connected.
- **Connected devices**: *polling, not websockets.* The sync task:
- sends `POST /devices/poll` every ~5s while the app runs (device TTL is
30s; commands TTL 20s) with our stable `device_id` (generated once,
persisted) and current `playback_state`;
- applies returned commands (`transfer_state` → load queue/position and
start/stop locally; play/pause/seek commands when we are the active
device but controlled remotely);
- feeds the device list into the Devices tab. Activating another device =
`POST /devices/active`; we then stop local audio and become a remote
control (UI keeps working, actions are sent via `POST /devices/command`).
- **Jams** (collaborative sessions) exist in the API — out of scope for v1,
but the sync task's command-handling design must not preclude them.
- **Fetching.** Feeds are fetched with conditional requests (ETag,
Last-Modified), bounded size (32 MiB per feed, 10 MiB per cover) and time
(15 s to connect, 60 s per request, 120 s for a whole fetch with its
redirects), and at most 10 redirects (http and https only) followed by
hand. The
address that the leading permanent hops (301/308) lead to becomes a feed
alias and the fetch URL, even when a temporary hop (CDN, tracker) follows
it; a chain that starts with a temporary hop never moves the feed.
Validators are dropped after a permanent redirect because they belong to
the old address. The prototype database's validators are dropped once at
import, so the first check parses the feed (seasons and episode numbers
were not stored by the prototype).
- **Scheduling.** The store keeps each feed's local fetch state (validators,
last error, consecutive failures, next check). A timer asks it which
subscriptions are due; feeds are checked at most a few at a time, a success
waits an hour, and failures back off exponentially (honouring
`Retry-After`). Errors never clear the stored catalog.
- **Runtime boundary.** Every store call, fetch and parse of the app runs on
the blocking pool or as a task and reports back through `AppEvent`s;
`update::podcasts` holds the pure state transitions. The device-sync
stream handlers call the store (snapshot export and merges) inside
`block_in_place`, so a store busy with a large feed refresh does not hold
a Tokio worker's other tasks; they are never called on the UI thread. Store open failures (newer schema,
foreign file) disable only the Podcasts tab and leave the file untouched.
- **Sync log.** Local actions (subscribe, unsubscribe, mark played, progress)
draw their operation stamps from the device-sync log through
`DeviceSync::run_podcast_action`, and the operations are appended with
exactly those stamps, so the store's registers and the log agree. The lock
order is podcast store, then sync log; device sync never calls the store
while it holds the log. Only the newest progress operation of an origin per
episode stays in the log (later operations of one origin always win the
register comparison).
- **Device sync.** Received podcast operations are kept in the log (and
relayed) and merged into the store with `PodcastStore::apply_remote_op`;
invalid ones are skipped but acknowledged. Operations that arrive before
the store opens wait in `sync_podcast_pending` and are applied when it is
attached. Snapshot sections are exported with `fill_snapshot` and merged
with `apply_snapshot` after the operations of the same message. The UI
reloads what it shows after such changes and checks the feed of a
subscription that came from another device.
- **Queue identity.** An episode is a `TrackItem` with an explicit
`podcast` reference (`TrackItem::podcast_episode`); its numeric id is a
shared sentinel and never identifies it. Queue keys check the episode id
first (`ep:…`), then music content ids, federated sources and library rows.
Music-only paths (likes, playlists, history, content-id resolution,
federation download, similarity, share links, metadata edits, release and
artist jumps) check `is_podcast()` and skip episodes. On the wire an
episode is `PlaybackSource::PodcastEpisode`; received ones become episodes
again (`TrackItem::from_playback_track`) and the library source mode never
drops them. Jam private placeholders are numbered queue entries that go
back on the wire as `PlaybackSource::Private`.
- **Playback.** Starting an episode resolves its current audio URL and
resume position from the store, opens `podcasts::stream` (a bounded
Range-request reader on its own thread), decodes and positions it with
coarse seeking, all off the UI and audio threads, then hands the source to
the audio thread with the player's source generation. Any later start or
stop bumps that generation, so a slow stream never replaces what the user
chose since. A stale audio URL (4xx) triggers one feed refresh and a retry
with the address the feed lists for the same episode id. A stream that
cannot seek does not start at a saved position it cannot reach, and seeks
in it (or in an episode still connecting) are refused. The stream is
cancelled by the same generation: a superseded start stops connecting or
reading up to its resume offset, and a read blocked on a stalled server
inside the audio callback returns within 100 ms, so it cannot hold the
audio thread past the next stop or start. The player does not report the
end of a superseded source. Pause and resume pressed while a source is
prepared update the intent it starts with.
- **End of a stream.** The reader records whether the decoder stopped on a
read error (lost connection, expired URL, cancellation) and whether the
server announced the file size. Only an end that the server described, or
one within the completion window, completes the episode and moves the
queue on; otherwise the last seen position is saved and playback stops on
the episode (`playback::played_to_the_end`).
- **Public discovery.** The federation node runs FRID's signed podcast
overlay (`music_dht::podcast_dht`, ALPN `furumi-fd/podcast-dht/1`, cache
`federation/podcast-dht.sqlite3`) next to the similarity overlay: it
serves the overlay, bootstraps, republishes and expires records, hands
every peer capability manifest to `note_peer_capabilities`, and advertises
`podcast_dht` in its own manifest only while the overlay runs. A cache
that cannot be opened is logged and only turns discovery off. What this
device publishes is decided by `podcasts::publication`: after local share
and unsubscribe actions (at once: `Reconciler::revoke_now`), received
podcast operations and feed refreshes (debounced 1 s), every overlay
(re)start and every 5 minutes it builds one
`PodcastShareState` per subscription (merged registers, a card from the
catalog for shared podcasts only, the local privacy confirmation) and
calls the declarative `PodcastDht::sync_shares`, which publishes what is
shared and tombstones every other own card. The share decision is the
synced `podcast_share_set` register, so share-off or unsubscribe on any
trusted device revokes every device's card and a stale device cannot
republish: until `DeviceSync::podcast_registers_current` turns true (a
sync exchange applied with a v4 device of the group after the podcast
store was attached, or no reachable v4 device in the group) a pass only
unpublishes the own cards its registers no longer share
(`publication::revoke_unshared`) and never calls `sync_shares`, whose
first call would re-send the cards FRID withholds from an earlier
session. Publication runs from each device's own identity. Privacy
confirmations of feed URLs that look private are device-local
(`podcast-share-confirmations.json`, mode 0600) and bound to the exact
URLs and to the share decision (the share register's operation): a newer
decision on any device drops them. Cards leave out artwork and web links
that look private, and both for a private-looking feed. Without a
readable podcast store this device revokes all its own cards. The report
of each pass lists the private podcasts whose own card is still live
(`unrevoked`: pending, failed or federation off) for the side panel; the
overlay peer count is refreshed every 10 s between passes. Before the
node stops on quit, `Reconciler::flush` waits up to 4 s for a revocation
requested just before. Logs carry counts only.
- **Finding and subscribing.** `Federation::search_podcasts`
(`podcasts::discovery::search`) runs `PodcastDht::search` as its own task,
bounded at 15 s including the overlay's bootstrap, apart from the music
search (`Federation::search`, unchanged), and delivers
`AppEvent::FedPodcastsLoaded` for the same search sequence, so music
results never wait for the overlay. The hits keep the podcast entries of
`merge_search_results` (exact titles first) as
`podcasts::discovery::PodcastHit`s. Off the UI thread each hit's origin
URL is resolved with
`PodcastStore::resolve_podcast_id`, and the "subscribed" mark compares
that id and the card's id with the subscribed podcasts, so a feed alias
counts. A card is a publisher's claim: only `PodcastSearchHit::feed_url`
(the origin URL the id is hashed from) is ever fetched, both for the
episode preview (`discovery::preview`, nothing stored) and for
«Подписаться» (`discovery::subscribe_from_hit` → `refresh::subscribe_url`),
which refuses a hit whose id does not match its URL and stores only what
the feed says. Claimed moved-feed URLs are displayed, never fetched or
recorded as aliases. The new subscription is private. Subscribing to an
address whose feed announces (`itunes:new-feed-url`) a newer one this
device already follows reports that subscription instead of adding a
second one, and the preview (`discovery::preview_for`) resolves the
address the feed moved to, so the card reads «Уже подписан» then.
- **Progress.** `podcasts::progress` runs one writer thread so every
progress write of this device is ordered. The app tick follows the
position and actual listening time and sends: an explicit start (or
"start over"), checkpoints every 20 s and on pause, explicit seeks (saved
once the audio thread reports that the seek worked,
`PlayerEvent::Seeked`), completion (`reaches_completion` or the real end
of the stream) and an end with the last
seen position on stop, track change, handoff and exit. When the store
reports a newer generation (another device started over, for example), the
playback stops checkpointing until the user's next explicit action.
Listening sessions are recorded at pause, completion and end; the store
keeps those that pass the shared threshold. Queue items carry the latest
progress generation this device saw, so a handoff target starts its
session above it.
## 5. Reliability checklist
## Scripted visualizations
- Terminal guard type + panic hook: raw mode/alternate screen/keyboard flags
always restored, even on panic.
- Every spawned task's failure becomes an `Event::TaskFailed` rendered as a
status-bar error — no silent hangs, no `unwrap` on I/O.
- Token refresh races guarded by a single-flight lock.
- Audio device disappearance (headphones unplugged) → backend emits
`PlayerEvent::Failed`, engine retries on default device, pauses on repeated
failure.
- Config/keymap parse errors are reported with line context and fall back to
defaults — a typo in keymap.toml must not brick the app.
Visualizations are an extension boundary rather than hard-coded rendering
paths. Rust owns audio sampling, script execution, validation, and terminal
drawing; Rhai scripts own the visual composition.
## 6. Suggested initial dependencies
```toml
[dependencies]
ratatui = "0.30"
crossterm = "0.29"
crokey = "1.4"
tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync", "time"] }
rodio = { version = "0.22", features = ["symphonia-aac", "symphonia-isomp4", "symphonia-alac"] } # check exact feature names
stream-download = { version = "0.24", features = ["reqwest"] }
reqwest = { version = "0.12", features = ["json", "rustls-tls"], default-features = false }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
toml = "0.8"
thiserror = "2"
anyhow = "1"
directories = "6" # config/cache paths per-OS
tracing = "0.1" # file-based logging (never stdout — it's the UI)
tracing-subscriber = "0.3"
```text
rodio source
│
v
audio analyzer ──> normalized features + scope samples
│
v
Rhai render(input)
│
v
validated draw commands
│
v
ratatui frame buffer
```
## 7. Build order (milestones)
The player analyzer derives a bounded, renderer-independent input model:
energy, bass, mid, treble, beat strength, waveform samples, playback progress,
volume, pause state, track metadata, time, and terminal dimensions. Each
script implements `render(input)` and returns declarative commands such as
clear, cell, line, rectangle, trace, and text. Scripts never receive the
ratatui frame or audio engine directly.
1. Skeleton: terminal guard, event loop, tab bar, status bar, keymap with defaults.
2. `api` crate-module: auth + artists/releases/tracks; Library grid → Artist → Release navigation.
3. Playback: rodio backend + stream-download, queue, now-playing bar, seek/volume.
4. Likes, playlists, search, history reporting.
5. Device sync: heartbeat/poll, transfer playback, remote-control mode.
6. Polish: server-side state restore, last.fm, config file, themes, optional cover art.
This command boundary is intentional:
- scripts remain independent of Rust UI internals;
- the host validates command shapes, colors, coordinates, and arrays;
- drawing is clipped to the current terminal area;
- script failures become an in-UI visualizer error instead of corrupting the
terminal or stopping playback.
Rhai files live in the user's visualization directory. The runtime discovers
them dynamically, compiles the selected script, caches its AST, and recompiles
it when the file modification time changes. A visualization can therefore be
created or edited while Furumi is running without rebuilding or restarting the
application. Bundled scripts use the same path and contract as user scripts,
so built-in and custom visualizations exercise the same runtime.
The v2 primitives are sufficient for small perspective wireframes without a
native 3D engine. The bundled morphing cube transforms eight vertices in Rhai
and batches its twelve edges into trace/vertical-line commands. Perspective,
audio-driven deformation, and depth cues stay in the user-editable script;
Rust rasterizes the resulting 2D commands. This deliberately avoids per-cell
script command maps and does not provide filled meshes or a depth buffer.
The richer cube preset adds bounded particle, ring, inner-cage, and echo
layers. Echo poses are reconstructed from earlier times with current audio
features, rather than retaining previous frames; particles have deterministic
lifetimes. Small terminals omit expensive layers and reduce particle counts.
The Rhai engine is configured as a sandboxed computation environment. Module
loading through `import` and `export` is disabled, no filesystem or network API
is exposed to scripts, and execution is bounded by limits on operations, call
depth, variables, functions, expression depth, and collection/string sizes.
Only the input map, Rhai language primitives, and a small set of mathematical
helpers are available.
The sandbox protects responsiveness and keeps visualization code in its
intended role: transforming current audio features into drawing commands. It
is not a plugin mechanism for accessing the library, network, or player
controls.
Fullscreen execution currently happens synchronously during UI drawing, with a fresh
Rhai scope for each frame; scripts should derive motion from time and the
already-smoothed audio features rather than rely on retained mutable state.
The 50 ms animation timer gives a nominal 20 FPS cadence (other events can
also trigger redraws). Operation limits are not wall-clock deadlines. The
host also checks the script modification time during drawing, so slow script
storage or expensive custom scripts can still delay input. Benchmark script
evaluation and buffer drawing separately from real terminal throughput before
increasing scene complexity or the refresh rate.
The embedded status surface uses the same Rhai engine, input map, command
decoder, and clipped buffer rasterizer with a one-row viewport. It has an
independent AST cache and a fixed user-editable script in
`visualizations/status/braille.rhai`, installed if absent. Exact copies of the
previous bundled default can be atomically upgraded; edited files are preserved. It is not a
fullscreen preset. During local playback the visual timer samples the audio
analyzer without increasing trusted-device publication frequency. At most
one blocking render job is in flight; excess ticks are dropped. File access,
compilation, evaluation, and buffer preparation happen on that worker.
An `AppEvent` delivers a prepared row to `AppState`; UI drawing only copies
cells. Its audio input comes from the decoded-source analyzer before output
volume scaling; the volume field remains informational. Pause suspends jobs
and retains the last frame, even when the row needs resizing. Generation
checks discard results invalidated by track changes, resize, pause/resume,
or stop. Script errors are confined to the row and retried so
editing the file repairs the display. Status scripts have a smaller operation
budget, bounded source/output sizes, and cannot draw outside their viewport.
## Music-similarity indexing
Similarity search is an optional local capability and is disabled by default.
When enabled, a background pipeline downloads a selected ONNX model, verifies
its pinned SHA-256 digest, decodes durable local tracks, and stores normalized
embeddings in the library SQLite database. Embeddings are keyed by an exact
fingerprint of the model artifact and preprocessing profile. Old profile rows
remain available while a new profile is calculated, and the in-memory exact
cosine index switches only after the replacement profile is usable.
The SQLite rows are the canonical derived store. The in-memory index can be
discarded and rebuilt, and neither is required for import, browsing, or
playback. Remote/cache-only tracks are never scheduled for local embedding.
Federated similarity uses a separate versioned direct-stream protocol. With
explicit privacy consent, the requester sends only a normalized embedding and
its profile fingerprint to a bounded set of known peers. It does not publish
queries to the DHT. Each peer searches its own active local index and returns a
bounded metadata result with a compact embedding SimHash. The requester uses
that signature to suppress near-duplicate recordings across peers without
receiving every result vector. Fan-out, concurrency, message sizes, and
timeouts are bounded; incompatible profiles are rejected. This direct
peer-selection layer can later be replaced by DHT routing without changing
local storage or ranking.
## Persistence boundaries
Furumi stores different kinds of state according to their lifetime:
| State | Storage | Role |
| --- | --- | --- |
| Library, playlists, likes, history | SQLite | Durable local source of truth |
| Podcast subscriptions, episodes, progress | SQLite (`podcasts.sqlite3`, FRID store) | Durable personal state (synced with trusted devices) and a refreshable episode catalog |
| Podcast share confirmations | JSON next to `podcasts.sqlite3` | Device-local consent to publish feed URLs that look private |
| Public podcast cards (own and replicas) | SQLite (`federation/podcast-dht.sqlite3`) | Discovery overlay cache; replaceable |
| Device operation log and replicas | SQLite | Offline synchronization |
| Versioned track embeddings | SQLite | Durable, locally rebuildable similarity data |
| Federation catalog cache | SQLite/cache | Faster network browsing |
| Audio and artwork cache | Filesystem cache | Reusable fetched data |
| Settings, keymap, identity | Platform config/data dirs | Node configuration |
| Queue and playback snapshots | Application/device sync state | Continuity and handoff |
Caches are replaceable. The local library, the podcast store's personal state
and the device operation log are durable.
This distinction lets maintenance and recovery code discard derived network
data without risking the user's collection.
## Failure model
Expected failures are treated as ordinary state:
- a DHT query may return partial results;
- an advertised peer may be offline by the time a track is requested;
- a transfer may stop and be retried through another source;
- trusted devices may reconnect with overlapping changes;
- cached metadata may be stale;
- an audio device may disappear during playback.
The architecture avoids converting these cases into global failure. Search can
show partial data, synchronization can resume, and playback resolution can try
another source. Errors return to the application as events so the UI can expose
them without terminating the node.
## Main implementation boundaries
The source tree follows the architectural responsibilities:
- `library/` owns the local catalog and import pipeline;
- `player/` owns audio playback and analysis;
- `similarity.rs` owns model acquisition, preprocessing, background indexing,
and the replaceable exact in-memory index;
- `federation/` owns DHT-facing search, peer catalogs, and audio exchange;
- `podcasts/` owns feed HTTP (conditional requests, redirects, limits),
refresh scheduling policy, the episode stream reader and the progress
writer, the publication of shared podcasts and subscribing from public
cards; the podcast model,
identity, merge rules, SQLite store and discovery overlay come from FRID;
- `devices.rs` owns trusted-device replication and playback coordination;
- `app/` owns state transitions and runtime orchestration;
- `ui/` renders the TUI;
- `media.rs` integrates platform media controls;
- `visualizer.rs` hosts programmable Rhai visualizations.
Dependencies should continue to point inward toward typed models and explicit
events. UI code should not own network tasks, network protocols should not
mutate UI state directly, and the local library should not depend on the
presence of federation.
## Architectural invariants
Future changes should preserve these rules:
1. A node must start and play its local library without network access.
2. No central Furumi service may become required for discovery, playback, or
trusted-device synchronization.
3. Federation membership must not imply personal-device trust.
4. Remote state must be merged or cached locally, never treated as an always
available database.
5. Network and storage work must remain outside the interactive UI path.
6. More peers should improve availability; losing peers should only reduce
remote capabilities.
+217
View File
@@ -0,0 +1,217 @@
# Changelog
All notable changes to Furumi are documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [0.5.0] - 2026-11-20
### Added
- Sharing a podcast in the federation (`Shift+F` in the `podcasts` context,
off by default): the synced share decision makes each device publish a
signed public card of the podcast in the FRID discovery overlay
(`podcast_dht`, advertised in the capability manifest); share-off and
unsubscribe revoke it with a tombstone. Feed URLs that look private are
published only after a confirmation on that device. The list and side
panel show whether a podcast is shared and whether this device publishes
it.
- Turning sharing off or unsubscribing revokes this device's card at once,
and quitting waits up to 4 s for that (also for a change still being
saved); the side panel says when a private podcast's card is not revoked
yet (pending or failed) or may not be (federation off: a card of an
earlier session cannot be ruled out). A privacy confirmation covers one
share decision: turning sharing off (or on again after that) on any
trusted device asks again, and until then this device holds the podcast
back and revokes the card it published for the earlier decision. A
confirmation whose decision could not be saved is dropped. Cards leave out
artwork and web links with an access key in the query or a member-feed
host (random-looking path parts of public CDNs are fine), and both for a
feed whose URL looks private.
- A device with other devices in its group publishes its cards only after
it synced with one of them since it started (or once none is left that
syncs podcasts), so a device that was closed while sharing was turned off
elsewhere does not send that card again; until then it only revokes, and
the side panel says it waits for a sync.
- Search (`/`, with the federation running) also finds public podcast cards.
They are listed after the music results under "Podcasts · public cards" with
a `[podcast]` marker, the number of publishing devices, and "✓ subscribed"
when this device is subscribed (also through a feed alias). The podcast
search runs apart from the federated music search (bounded at 15 s), so
music results never wait for it; local-only search is unchanged.
- Enter on a podcast hit opens its card: title, author, categories,
description, episode count, newest episode, publishing devices, feed URL
and unverified moved-feed claims. `e` reads the seasons and episodes from
the feed without subscribing. «Подписаться» (Enter) subscribes privately
with the card's origin feed URL, so the podcast id is the card's, and
reads everything from the feed itself; «Уже подписан» opens the podcast
in the Podcasts tab instead, also when this device follows the feed under
the newer address it moved to (known once the feed was read), and
subscribing to such an older address adds no second subscription.
- A Podcasts tab on `4`: subscribe to RSS/Atom feeds by URL, browse
podcast → seasons → episodes with saved position, played state, duration and
date, search episodes, filter by listening state, change the order, mark
episodes played or unplayed, check one or all feeds, and unsubscribe (progress
and history are kept). Feeds are checked in the background with conditional
requests and back-off; permanent redirects become feed aliases.
- Podcast data uses the shared FRID store (`furumi_library::podcasts`) in
`podcasts.sqlite3`; a database of the earlier podcast test build is migrated
in place, and a newer or foreign file is refused without changes.
- Podcasts sync between trusted devices (device-sync protocol 4):
subscriptions, unsubscribing, feed addresses, episode progress ("played",
position, "start over") and listening sessions. A podcast subscribed on one
device appears on the others without its URL; each device checks the feed
itself. Podcast operations are applied to the podcast store, kept in the
sync log and relayed; snapshots carry the podcast state (bounded) so new
devices and devices that upgrade from an older version catch up. Periodic
progress saves are coalesced in the log.
- A queue with podcast episodes is handed to other devices with the episode,
its position and pause; the receiving device does not need the
subscription.
- Podcast episodes play from the Podcasts tab and the shared queue (mixed
with music): audio streams from the publisher through a bounded HTTP Range
buffer, Play continues from the saved position, `b` starts over, and the
position is saved every 20 s and on pause, seek, stop, track change and
exit. Completion and listening sessions follow the shared FRID rules. A
stale audio URL triggers one feed check for the episode's new address. A
lost connection stops playback at the saved position (the episode is not
completed and the queue does not move on). Without a file size from the
server, a closed stream counts as the end within the completion window of
the duration the audio file states, or past 80 % of a duration only the
feed announced; a superseded or stalled stream
is cancelled at the next start or stop; pause pressed while an episode
connects is kept; seeks that do not move the audio are not saved.
- Podcast key bindings in the `podcasts` context: `o`, `/`, `Shift+R`,
`Ctrl+R`, `Shift+S`, `f`, `m`, `Shift+U`, `b`.
- An optional top-level `version` in `keymap.toml`; the current format is
`version = 2`, and a `podcasts` binding context.
### Changed
- `furumi-tui` 0.5.0.
- Use published `music-dht` 0.6.0 and `furumi-library` 0.3.0 from crates.io;
remove the temporary FRID fork patches.
- Self-update and release download links use the canonical
`Furumi-stack/furumi-tui` GitHub repository.
- Queue items are keyed by their source: podcast episodes by episode id,
library rows as `lib:<id>` instead of `local:<id>`. Likes, playlists,
music history, similarity, share links and metadata edits skip episodes.
- Device sync speaks protocol 4 and uses the shared `music_dht::device_sync`
wire types instead of private copies; v3 messages are unchanged byte for
byte (golden tests). Devices below protocol 4 never receive podcast
operations, podcast snapshot sections or a queue with episodes: handing
such a queue to them is refused ("needs a Furumi update"), and their
playback commands are ignored while the queue has episodes. They still get
the playback coordination, with each episode shown as "Private item", so
they do not take playback over after two minutes of silence. When such a
device does take over, the "Private item" entries it echoes back as music
are left out of the queue here, with a status message.
- Jam guests see the host's podcast episodes as "Private item" (no title,
feed or address). Guest changes that add, drop or duplicate them, or seek
in them, are refused; a guest leaving a Jam drops the placeholders.
- Controlling another v4 device may queue and play episodes there; an
episode started by another device's command at position 0 resumes from its
saved position.
- Tab order is now `1` Library, `2` Playlists, `3` Queue, `4` Podcasts,
`5` Settings, `6` Logs, for the tab bar, Tab/Shift+Tab, and the default
number keys.
- Keymap files without `version` keep their tab shortcuts: `GoToTab` indices
are remapped in memory (3 → 4 Settings, 4 → 5 Logs, and 5 → 3 Podcasts
from the prototype podcast build) with a non-blocking startup notice. The
file is not rewritten; `version = 2` files are used as written. A `version`
key placed inside a `[[keymaps]]` entry is reported as an error instead of
being ignored.
- The tab bar shortens titles, then shows only numbers (keeping the active
tab's full title) on terminals too narrow for all six tabs.
- A keymap notice no longer hides a "logging disabled" startup warning; both
are shown.
- The help window names the target tab for number-key shortcuts
("Go to Settings") instead of "Go to tab N".
### Fixed
- Isolate log privacy and identity-lock lifecycle tests from process-wide
state and descriptor inheritance in parallel tests.
- The protocol version stored for another device came from this build's own
constant (on profile announcements and accepted pairings), not from the
device. Versions now come from the device's own reports; relayed profiles
only raise them. Invites and profile announcements carry the version, and
the first start of a new version announces it.
## [0.2.8] - 2026-09-02
### Added
- Optional offline music-similarity search for local tracks, backed by
versioned SQLite embeddings and a replaceable exact in-memory cosine index.
- Automatic SHA-256-verified download and local inference for the first ONNX
embedding model, with retained model/profile generations and background
backfilling of existing library tracks.
- Similarity settings for enablement, model/profile information, numeric worker
count, derived-data cleanup, processing progress, and federation privacy
consent.
- Track-seeded similarity search from the track-information popup, including
bounded federated queries to compatible known peers.
- The `furumi-fd/similarity/1` protocol in the visible protocol-version status.
- Decentralized `similarity_dht` routing with signed anonymous two-level LSH
summaries, multi-probe lookup beyond the locally known peer set, and known-
peer fallback during gradual network upgrades.
### Changed
- Similarity wire types, bounds, validation, and stream framing now come from
the shared `music-dht 0.4` API so native, web, and future clients can
interoperate without sharing an embedding implementation.
- Existing SQLite embeddings are backfilled once with compact 256-bit routing
signatures; new embeddings store them immediately without changing exact
local cosine search.
- A similarity result page keeps the source track first as query context while
excluding it from the actual nearest-neighbor ranking, labels the mode as
`Search similar to`, and suppresses near-identical embeddings across releases
and federated peer responses.
- Preprocessing profiles now open a read-only details window describing their
audio selection, resampling, spectrogram, patching, and aggregation contract.
### Fixed
- Federation now recovers automatically after sleep, prolonged idle, or a
degraded rendezvous transport while preserving local playback and state.
- Current-track information (`Shift+I`) now uses the enriched queue entry, so
it shows the same complete metadata and similarity action as `I` on that
track in the queue.
## [0.2.5] - 2026-08-02
### Added
- Command history navigation with the Up and Down arrow keys.
- A copy-friendly plain terminal view for connection tickets, device and Jam
invites, and track-sharing links.
- A configurable permanent music directory with write validation and an
optional safe migration of existing Furumi-managed files.
- Queue reordering for one track or a `Shift+V` selection with `Alt+K` and
`Alt+J`.
- Reproducible Nix/devenv tooling with Rust 1.97 and ALSA development files.
### Changed
- Sequential `a` actions now build one ordered play-next block instead of
reversing independently inserted tracks.
- Federated artist images and release covers are stored beside permanent music
in an `Artist/Release` directory tree.
### Fixed
- Running a development build next to another Furumi instance no longer lets
an MPRIS name collision disable terminal raw mode and freeze keyboard input.
- `nix develop` now keeps devenv state outside the read-only Nix store and
isolates Rust 1.97 build artifacts from other toolchains.
- Music-directory validation and migration now reject overlapping changes,
resolve canonical paths, and produce Windows-portable managed filenames.
[Unreleased]: https://gt.hexor.cy/ab/furumi_tui/compare/v0.2.8...HEAD
[0.2.8]: https://gt.hexor.cy/ab/furumi_tui/compare/v0.2.7...v0.2.8
[0.2.5]: https://gt.hexor.cy/ab/furumi_tui/compare/v0.2.4...v0.2.5
Generated
+3206 -934
View File
File diff suppressed because it is too large. Load diff
+39 -8
View File
@@ -1,40 +1,71 @@
[package]
name = "furumi_tui"
version = "0.1.3"
version = "0.5.0"
edition = "2024"
rust-version = "1.97"
description = "A federated P2P player for personal music libraries"
license = "WTFPL"
[[bin]]
name = "furumi"
path = "src/main.rs"
[dependencies]
rustls = { version = "0.23", default-features = false, features = ["ring", "std", "tls12"] }
semver = "1"
self-replace = "1.5"
tempfile = "3"
fs2 = "0.4"
flate2 = "1"
tar = "0.4"
zip = { version = "4", default-features = false, features = ["deflate"] }
object = { version = "0.36", default-features = false, features = ["read", "std"] }
anyhow = "1.0.102"
arboard = { version = "3.6.1", default-features = false, features = ["wayland-data-control"] }
blake3 = "1"
crokey = "1.4.0"
crossterm = { version = "0.29.0", features = ["event-stream"] }
directories = "6.0.0"
futures-util = "0.3.32"
furumi-library = "0.3.0"
image = { version = "0.25.10", default-features = false, features = ["jpeg", "png", "webp", "gif", "bmp"] }
open = "5.3.5"
ratatui = "0.30.1"
reqwest = { version = "0.13.4", default-features = false, features = ["json", "rustls"] }
lofty = "0.22"
# P2P federation: library index in a shared DHT + audio streaming between
# peers (same protocol as furumi-fd).
music-dht = { version = "0.6.0", features = ["podcast-feed"] }
ratatui = { version = "0.30.1", features = ["unstable-rendered-line-info"] }
reqwest = { version = "0.12.28", default-features = false, features = ["rustls-tls", "stream", "blocking"] }
rhai = { version = "1", features = ["sync"] }
rodio = { version = "0.22.2", default-features = false, features = ["playback", "mp3", "flac", "vorbis", "wav", "symphonia-aac", "symphonia-isomp4", "symphonia-alac"] }
rusty-opus = "0.9.1"
rustfft = "6.4.1"
rusqlite = { version = "0.32", features = ["bundled", "functions"] }
serde = { version = "1.0.228", features = ["derive"] }
serde_json = "1.0.150"
sha2 = "0.10.9"
souvlaki = { version = "0.8.3", default-features = false, features = ["use_zbus"] }
stream-download = { version = "0.24.1", default-features = false, features = ["reqwest-rustls", "temp-storage"] }
symphonia = { version = "0.5.5", default-features = false, features = ["ogg"] }
thiserror = "2.0.18"
tokio = { version = "1.52.3", features = ["rt-multi-thread", "macros", "sync", "time"] }
tokio = { version = "1.52.3", features = ["rt-multi-thread", "macros", "sync", "time", "fs", "io-util"] }
toml = "1.1.2"
tracing = "0.1.44"
tracing-subscriber = { version = "0.3.23", features = ["env-filter"] }
tract-onnx = "0.23.4"
unicode-width = "0.2.2"
[patch.crates-io]
# souvlaki 0.8.3 still depends on the unmaintained block 0.1.6. Keep its API
# intact while using an opaque inhabited FFI type accepted by current Rust.
block = { path = "vendor/block" }
[target.'cfg(target_os="macos")'.dependencies]
core-foundation = "0.10.1"
[target."cfg(windows)".dependencies]
windows-sys = { version = "0.61.2", features = ["Win32_Foundation", "Win32_UI_WindowsAndMessaging", "Win32_System_LibraryLoader", "Win32_Graphics_Gdi"] }
windows-sys = { version = "0.61.2", features = ["Win32_Foundation", "Win32_UI_WindowsAndMessaging", "Win32_System_LibraryLoader", "Win32_Graphics_Gdi", "Win32_System_Console", "Win32_System_Pipes"] }
[target."cfg(unix)".dependencies]
libc = "0.2.186"
[dev-dependencies]
base64 = "0.22.1"
+13
View File
@@ -0,0 +1,13 @@
DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
Version 2, December 2004
Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
Everyone is permitted to copy and distribute verbatim or modified
copies of this license document, and changing it is allowed as long
as the name is changed.
DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. You just DO WHAT THE FUCK YOU WANT TO.
+437 -136
View File
@@ -1,186 +1,487 @@
# furumi
![furumi TUI screenshot](furumi.png)
![furumi](furumi.png)
`furumi` is a cross-platform terminal client for a furumusic server. It
provides a fast TUI for browsing the library, playing music, managing the
queue and playlists, controlling devices, and inspecting logs without leaving
the terminal.
**Your music. Your devices. Your network.**
## Features
Furumi is a federated P2P player for your personal music library. Every
running player is a complete, self-sufficient music library: it can import,
organize, search, and play your collection without an account, a cloud
backend, or a central service.
- Browse the full artist library in tile or table view.
- Open artist pages, releases, and track lists from inside the TUI.
- Search artists, releases, and tracks with `/`.
- Play local audio with seek, volume, shuffle, repeat, and like controls.
- Add tracks next in queue, append them to the queue, or clear the queue.
- Browse playlists, liked tracks, and add tracks to playlists.
- Pick the active playback device and control remote devices.
- Use OS media keys through MPRIS/system media controls.
- Inspect live in-app logs and a persistent log file.
- Customize key bindings with a TOML keymap.
Connect Furumi on your desktop, laptop, or another device and they become one
personal music network. Playback, likes, playlists, and library state can move
between your devices, while missing tracks can be requested directly from
another player.
## Installation
Furumi runs on **Linux, macOS, and Windows**.
Requires Rust 1.88+.
## Why Furumi?
Music you own should not disappear because a subscription ended, a catalog
changed, a service was censored, or a server went offline.
Furumi is built around a different model:
- your library remains under your control;
- every player works independently;
- there is no central account or single point of failure;
- connecting more players improves availability instead of creating a new
dependency;
- federation is optional and simple to configure.
A single Furumi instance is already useful. A group of instances becomes a
resilient network for your music.
## How it works
Each player maintains its own local library and publishes a searchable view of
it into Furumi's DHT network. Discovery does not depend on a central index.
Clients connect directly over P2P transport built on
[iroh](https://www.iroh.computer/). Furumi adds a synchronization protocol on
top of that transport to keep trusted devices consistent even when they are
not always online.
In practice:
1. Import music into any Furumi player.
2. Pair your other players or join a federation network.
3. Devices discover available libraries through the DHT.
4. Likes, playlists, playback state, and library metadata synchronize between
trusted clients.
5. If a track is missing locally, Furumi can fetch it directly from another
client.
There is no coordination server in the middle. Local players remain usable
when peers are offline, and the network becomes more capable as peers appear.
## The player
Furumi includes a full-featured terminal interface for browsing artists and
releases, searching, managing playlists and the queue, controlling playback,
inspecting connected devices, and configuring federation.
The interface supports keyboard-driven navigation, multi-key combinations,
context-aware bindings, and user-defined rebinding through TOML. Built-in
audio visualizations, OS media controls, gapless queue playback, and local
library management are included. Visualizations are runtime-loadable Rhai
scripts executed in a resource-limited sandbox, so they can be added or edited
without rebuilding the player.
Optional similarity search calculates versioned embeddings for local tracks
in the background and keeps them in SQLite. It works offline; after a separate
privacy consent it can also ask a bounded set of federation peers for matches.
Compatible peers are selected through signed, anonymous LSH summaries in a
decentralized DHT; no central recommendation index or shared calibration file
is required.
The first selectable model is downloaded on demand and is licensed separately
by MTG under CC BY-NC-SA 4.0 (a proprietary license is also available from
MTG); Furumi itself remains WTFPL.
## Install
### macOS
On Apple Silicon Macs, install Furumi from the Homebrew tap:
```bash
cargo build --release
brew install house-of-vanity/tap/furumi
```
Run it with:
```bash
furumi
```
### Linux, Windows, and other platforms
Download a prebuilt archive from the
[GitHub releases](https://github.com/Furumi-stack/furumi-tui/releases), or
build Furumi from source with Rust 1.97 or newer:
The repository selects the stable Rust toolchain. With rustup, run
`rustup update stable` to install or update it before building.
```bash
cargo build --release --locked
./target/release/furumi
```
The release binary is named `furumi`:
On Debian or Ubuntu, install the Linux audio build dependencies first:
```bash
cargo run --release --bin furumi
```
### Linux
Audio output needs the system ALSA library. PipeWire and PulseAudio are used
through the ALSA compatibility layer at runtime.
```bash
# Debian / Ubuntu
sudo apt install libasound2-dev pkg-config
# Fedora
sudo dnf install alsa-lib-devel pkgconf-pkg-config
# Arch
sudo pacman -S alsa-lib pkgconf
```
Everything else is handled by Rust dependencies: TLS uses `rustls`, MPRIS uses
`zbus`, and image/audio decoding is provided by Rust crates.
Equivalent ALSA development packages are required on other Linux
distributions. macOS and Windows require no additional system packages.
### macOS and Windows
Import a music directory from Furumi's command line:
No extra system packages are required.
```text
:import /path/to/music
```
## First Run
Federation, trusted-device pairing, and key bindings are configured directly
inside the player.
On startup, `furumi` opens the login screen:
### Manual updates
1. Enter your furumusic server URL.
2. Sign in with username/password or SSO.
3. After a successful login, the session is saved locally.
In **Settings → Additional settings → Updates**, select **Check for updates**, then **Install update**
when a newer stable GitHub release is available. Downloads run in the background.
After installation, restart `furumi` to use the new version; playback is not
restarted automatically. Wait for an active update operation to finish before
quitting.
The SSO flow opens your browser automatically. If the loopback callback is not
available, `furumi` shows the URL and accepts either a pasted `furumi://...`
callback link or the short `furu_mx_...` code.
Updates replace the running executable in its installation directory, which
must be writable by your user. Release archives must include a matching entry
in the release's `SHA256SUMS` asset. Older releases without it cannot be installed
through this feature. The updater checks SHA-256 and the executable's format
and architecture before replacing it. Checksums provide integrity checking,
not publisher signatures. Settings and the local library are preserved.
## Controls
There are no automatic startup checks. Only the existing release asset naming
scheme is supported; missing or incompatible platform builds are rejected.
Common key bindings:
The **Additional settings** window also contains the music save directory and
visualization controls. Use Up/Down (or j/k) to navigate, Enter to select, and
Esc to return to Settings. Long lists scroll with the selection.
| Key | Action |
### Tabs and key bindings
The number keys open the tabs in the order they are shown, and Tab /
Shift+Tab cycle through them:
| Key | Tab |
| --- | --- |
| `?` | Show key binding help |
| `q`, `Ctrl-C` | Quit |
| `Tab`, `Shift-Tab` | Next / previous tab |
| `1`...`4` | Jump to a tab |
| `j` / `k`, arrows | Move down / up |
| `h` / `l`, arrows | Move left / right |
| `Enter` | Open or select item |
| `Esc`, `Backspace` | Go back |
| `Space` | Play / pause |
| `n`, `p` | Next / previous track |
| `.`, `,` | Seek 10 seconds forward / backward |
| `+`, `-` | Volume up / down |
| `s` | Toggle shuffle |
| `r` | Cycle repeat mode |
| `x` | Like / unlike |
| `a` | Add track next |
| `Shift-A` | Add track to the end of the queue |
| `Shift-P` | Add track to a playlist |
| `Shift-D` | Open device picker |
| `v` | Toggle tile/table view |
| `/` | Search |
| `:` | Open command line |
| `1` | Library |
| `2` | Playlists |
| `3` | Queue |
| `4` | Podcasts |
| `5` | Settings |
| `6` | Logs |
Command line examples:
On narrow terminals the tab bar shortens titles and then shows only the
numbers, keeping the active tab's full name. Press `?` for the full list of
bindings and commands.
```text
:q
:logout
:volume 40
:seek +30
:seek -10
:seek 1:30
:shuffle
:repeat off
:repeat one
:repeat all
:clear
:next
:prev
:play
:pause
:devices
:logs debug
```
Bindings can be overridden in `keymap.toml` in the platform config directory
(`~/.config/furumi/keymap.toml` on Linux,
`~/Library/Application Support/furumi/keymap.toml` on macOS); the bundled
`src/config/default_keymap.toml` documents the format. Start the file with
`version = 2`, the current format: its `GoToTab` indices are used exactly as
written (`0` Library … `5` Logs). `version` must come before the first
`[[keymaps]]` entry; written after one, TOML would attach it to that entry, so
Furumi rejects such a file with an error instead of guessing. Files without `version` were written for the
older tab order (Settings and Logs on `4`/`5`, Podcasts on `6` in the
prototype podcast build); Furumi adapts their tab shortcuts in memory so they
keep opening the same tabs, shows a short notice at startup, and never
rewrites the file. Add `version = 2` once the indices match the new order to
take them literally and silence the notice.
## Configuration
### Podcasts
`furumi` stores configuration in the platform app config directory:
The Podcasts tab (`4`) follows RSS and Atom podcast feeds. Furumi stores only
the feed's episode information; audio stays on the publisher's server and is
never imported into the music library or offered to other peers.
- Linux: `~/.config/furumi`
- macOS: `~/Library/Application Support/furumi`
- Windows: `%APPDATA%\furumi`
- **Add podcast** (`o`, or the first row) takes a feed URL; `feed://`,
`podcast://` and URLs without a scheme are accepted. Nothing is stored unless
the URL serves a feed. New subscriptions are private.
- The list shows each podcast's unplayed and total episode counts and its
check status; `!` marks a podcast whose last check failed, with the error in
the side panel (or below the list on narrow terminals).
- `Enter` opens a podcast. Podcasts with seasons show their seasons first
(plus "All episodes" and "Without a season"); `Esc` goes back.
- Episodes show the date, season/episode number, duration and listening
state: `●` not started, `◐` in progress with the saved position, `✓` played.
`/` searches titles and descriptions, `f` cycles all / unplayed / in
progress / played, `Shift+S` changes the order, `m` marks the selected
episode played or unplayed.
- `Shift+R` checks the selected podcast for new episodes, `Ctrl+R` checks all
of them. Feeds are also checked in the background about once an hour with
conditional requests; a failing feed is retried with growing pauses and its
known episodes stay available. A permanent redirect moves the subscription
to the new address.
- `Shift+U` (or `Shift+D`) unsubscribes after a confirmation. Listening
progress and history are kept, so subscribing again continues where you
left off.
- `Shift+F` shares the selected (or opened) podcast in the federation, or
makes it private again. The list marks shared podcasts with `shared`, and
the side panel says whether this device publishes the card (see
"Sharing a podcast" below).
Important files:
Episodes play in the same queue as music:
- `credentials.json` - saved login session. On Unix it is written with `0600`
permissions.
- `device_id` - stable identifier for this TUI client during device sync.
- `keymap.toml` - user key binding overrides.
- `Enter` on an episode plays it right after the current item and continues
from the saved position; a played episode starts from the beginning. `b`
("start over") plays it from the beginning even when it is in progress.
`a` / `Shift+A` queue episodes like tracks, and the queue can mix music and
episodes.
- Audio streams from the publisher's server through a bounded buffer (about
9 MB) and seeks with HTTP range requests. Nothing is downloaded ahead of
time and nothing is kept after playback. If the server cannot seek (no
file length), Furumi says that it cannot continue at the saved position
instead of starting from the wrong place; "start over" still works, and
seeking in such an episode is refused with a message. If the episode's
address no longer works, the feed is checked once for a new one.
- If the connection is lost during an episode (no data for 30 seconds, or
the address stops working), playback stops there: the position is saved,
the episode is not marked played and the queue does not move on; play
continues from that position. A pause pressed while an episode is still
connecting is kept when the audio arrives.
- Some servers send episodes without a file size. There a closed connection
looks like the end of the file, so Furumi compares the position with the
episode's duration: the one the audio file states, or else the
`itunes:duration` of the feed. Feed durations are often a little off, so
reaching 80 % of one is enough; an episode that stops earlier is treated as
a lost connection. Such servers do not allow seeking either, so play cannot
continue in the middle: start the episode over (`b`) or mark it played
(`m`).
- The position is saved every 20 seconds while playing and on pause, seek,
stop, track change and exit. An episode counts as played within the last
30 seconds (or 5 %) or when its stream reaches its end; a listen enters the episode's
history when it completed or lasted at least 30 seconds. Seeking back and
"start over" are real changes: an older save never moves the position
forward again.
- Likes, playlists, music history, similarity search and share links are for
music only and skip episodes; `Shift+J` on an episode opens its podcast.
See [`src/config/default_keymap.toml`](src/config/default_keymap.toml) for the
default format. Example:
Podcasts and your connected devices:
```toml
[[keymaps]]
key_sequence = "ctrl-n"
command = "NextTrack"
- **Private by default.** Subscriptions, episode progress and listening
history are personal. They are synchronized only between your trusted
devices (Connected Devices), never published to the federation: no DHT
record, public catalog or search result contains them. Publishing a
podcast for discovery is a separate, explicit choice (`Shift+F`, below).
- **Synchronized between trusted devices.** A podcast you subscribe to on
one device appears on the others without typing its URL again; each
device then checks the feed itself. Unsubscribing, "played", the saved
position and "start over" follow the same way, also through a device
that relays them and after a device was offline for a while. When two
devices played the same episode offline, they agree on one position and
keep both listening sessions.
- **Handoff.** A queue with episodes moves to another device like music:
the episode continues there at the handed-off position, paused or
playing, even if that device is not subscribed. Devices that run an older
Furumi (device sync before v4) cannot keep episodes: handing such a queue
to them is refused with "needs a Furumi update", their remote control is
ignored while the queue has episodes, and they get no podcast data: they
see such a queue with "Private item" in place of each episode, so they
keep seeing this device as the playing one. An older device still takes
over when you choose it as the output (Play on it), when it starts while
this device is paused (`take_paused_on_startup`), or by itself once this
device has been closed, asleep or offline for about two minutes. Its queue
then has an unplayable "Private item" music entry for each episode; this
device shows that queue without them (with a status message), and the
episodes' saved positions stay.
- **Audio from the publisher.** Every device streams the episode from the
publisher's server itself. Furumi peers never pass podcast audio to each
other, and nothing is kept after playback.
- **Jam.** Guests see the host's episodes as "Private item" (no title, feed
or address), cannot add episodes to the host's queue and cannot seek in a
private item. They can still reorder the queue and skip.
[[keymaps]]
key_sequence = "ctrl-f"
command = { SeekForward = { seconds = 30 } }
```
Sharing a podcast (public discovery):
A user binding replaces the default binding with the same key sequence and
context.
- `Shift+F` turns "share in the federation" on for one podcast. The choice is
synchronized to your trusted devices like a subscription; each of your
devices that runs the federation then publishes a small public card of the
podcast under its own device key: the feed URL, title, author,
description, artwork and web links, the number of episodes and the date of
the newest one. The card never contains your progress, history, play
counts, device names or anything from podcasts you did not share. Artwork
and web links that look like they carry an access key (a token, key or
signature in the query, a member-feed host) are left out, and so are both
for a feed whose own URL looks private. Random-looking parts of their
path alone do not count: public podcast hosts name artwork that way.
- If the feed URL looks private (a token, key or signature in its query, a
member-feed host such as Patreon, a long random-looking part), Furumi asks
first and lists why (in Russian). Anyone who finds the card can read the
feed at that URL. The confirmation is stored only on this device
(`podcast-share-confirmations.json` next to `podcasts.sqlite3`) and covers
exactly the URLs shown and this one decision to share: another device of
yours asks again before it publishes, and so does this one if the feed
moves or if sharing is turned off (or turned on again after that) on any
of your devices. Until then the side panel says the publication is held
back, and a card this device published for the earlier decision is
revoked; press `Shift+F` there to confirm (or `x` in the dialog to stop
sharing). A confirmation whose decision could not be saved is dropped.
- `Shift+F` on a shared podcast, or unsubscribing, makes it private again on
every device in your group: each device replaces its card with a signed
removal record. This device sends its removal right away, and quitting
waits for it (up to 4 seconds, also when you quit before the change is
saved) and logs a warning when a card may still be live. While the
removal is not sent yet (or could not be sent), the side panel says the
public card is not revoked yet instead of just "private". With the
federation off this device cannot tell whether a card of an earlier
session is still live, so for a podcast that was shared the panel says
the card may not be revoked yet; the removal is sent the next time the
federation runs. Until then, and for a copy that missed the removal, the
card can still be found until it expires (at most 12 hours). Removing your card never touches other
people's subscriptions. An older device that comes back with the earlier
"share" decision does not publish it again: after starting, a device with
other devices in its group publishes nothing until it has synced with one
of them (the side panel says "waiting for a sync with your other
devices"); it still revokes at once what its own decisions no longer
share. Devices of your group that still run Furumi 0.3 (they do not sync
podcasts) and devices without an address are not waited for; remove a
device you no longer use under Connected Devices so this one stops
waiting for it.
- A device that left your device group, or was removed from it, no longer
receives your share decisions: it keeps publishing the podcasts it shares
until you turn sharing off (or unsubscribe) on that device itself.
- The card is signed with this device's federation key, which is also the
key of its public music library, so a shared podcast can be linked to
that library and to the device's network address.
- Publishing needs the federation to be running; the side panel shows
"not published" with the reason otherwise.
## Logs
Finding public podcasts:
The Logs tab shows a live in-memory ring buffer inside the TUI. You can jump
to it and set the level filter with:
- The search (`/` outside the Podcasts tab, with the federation
running) also looks for public podcast cards. They are listed after the
music results under "Podcasts · public cards", each marked `[podcast]`,
with the number of devices that publish the card (devices, not
subscribers; anyone can create devices, so it is not a sign of trust) or
"✓ subscribed" when this device already follows the podcast, also when
you subscribed under an older address of the same feed that moved to the
card's address. When you follow the feed under a newer address than the
card's, the list cannot tell yet; the card can once its episodes are read
(`e`), and «Подписаться» never adds a second subscription for it. Your
query words go to the discovery peers, as they do for music search. The
podcast search runs apart from the music search (music results never wait
for it) and gives up after 15 seconds. With the federation off, search
stays local and shows no podcasts.
- Enter opens the card (in Russian): what its publishers claim (title,
author, categories, description, number of episodes and date of the
newest one), the feed URL, and addresses some publishers claim the feed
moved to, shown as unverified and never used. `e` reads the feed itself
and lists its seasons and episodes without subscribing; this is a request
to the podcast's own server, not to the publisher.
- «Подписаться» (Enter) subscribes with the card's feed URL, the address
the podcast's id is derived from, so the podcast is the same one the
publisher shares. Furumi then reads the feed from its own server and
stores only what the feed says; the publisher does not need to stay
online, and nothing from the card is kept. The new subscription is
private like any other: it is not shared until you press `Shift+F`, and
your progress is your own. «Уже подписан» means this device is already
subscribed (under the card's address, an older one, or — once the feed
was read — the newer address the feed moved to); Enter then opens the
podcast in the Podcasts tab.
```text
:logs error
:logs warn
:logs info
:logs debug
:logs trace
```
Podcast data lives in `podcasts.sqlite3` in the platform data directory (the
same file the earlier podcast test build used; it is upgraded in place). If
that file was written by a newer Furumi or is not a podcast database, the tab
explains why it is unavailable and the file is left unchanged; podcast
changes from other devices then wait in the device-sync log until it opens.
The persistent log file is written to the platform cache directory as
`furumi-cli.log`. File logging is filtered by `RUST_LOG`:
### Now playing in tmux
While Furumi is running, a second invocation can print a cheap, single-line
playback snapshot without opening the TUI or library:
```bash
RUST_LOG=furumi_tui=debug cargo run --release --bin furumi
furumi --status
# ▶ Artist — Track 1:23/4:05
```
For example, add this to `.tmux.conf`:
```tmux
set -g status-interval 1
set -g status-right '#(furumi --status) | %H:%M'
```
`furumi --status-json` returns the same snapshot as JSON, including playback
state, title, artist, album, position, duration, and volume. Both commands
print nothing when Furumi is stopped or no track is loaded. On Linux, Furumi
also exposes the existing MPRIS player `cy.hexor.furumi`, which can be queried
with tools such as `playerctl`.
## Architecture
At a glance:
Furumi is a Rust application built with:
- UI: `ratatui` + `crossterm`.
- Runtime: `tokio`.
- HTTP: `reqwest` + `rustls`.
- Audio: `rodio` + `stream-download`.
- Keymap config: `crokey` + TOML.
- State model: one `AppState`, events, and an update loop.
- `ratatui` and `crossterm` for the cross-platform TUI;
- `rodio` for local audio playback;
- SQLite for the personal library and synchronization state;
- tract ONNX inference for optional local music embeddings;
- a dedicated DHT for decentralized discovery;
- iroh-based P2P streams for client-to-client communication;
- an offline-tolerant operation log for trusted-device synchronization;
- Rhai for programmable audio visualizations.
See [`ARCHITECTURE.md`](ARCHITECTURE.md) for more detail.
More detail is available in [ARCHITECTURE.md](ARCHITECTURE.md).
## Contributing
Bug reports, design discussions, and patches are welcome. Before submitting a
change, run:
```bash
cargo fmt --all -- --check
cargo check --all-targets
cargo test --all-targets
```
## Playback coordination
Connected Devices uses the shared `music_dht::playback` engine from frid.
Newly started players take an idle/paused output after discovery and become
controllers when another device is playing. Missing output reports trigger
automatic failover; concurrent claims converge to one owner. The web gateway
uses a passive server profile and reports actual browser activity.
Only one TUI process may use a device identity. Installed and locally built
binaries use the same user data directory: close the installed player before
starting a development build. An OS file lock prevents duplicate coordinators
and is released automatically on exit or a crash. Older builds do not take
this lock, so close those explicitly when upgrading.
Connected-device polling runs independently per peer, so an offline or stalled
device does not postpone updates to live players.
The existing device menu handles manual transfers. Advanced policy can be set
in `settings.toml` without changing the UI:
```toml
[playback]
claim_on_startup = true
automatic_failover = true
take_paused_on_startup = true
discovery_ms = 3000
owner_timeout_ms = 120000
```
All clients must support the new coordination envelope for eventual single
output ownership. frid's `PLAYBACK_PROTOCOL.md` describes the protocol, adapter
contract and rollout. This release uses the published FRID crates
`music-dht 0.6.0` and `furumi-library 0.3.0` from crates.io.
Run the local protocol checks from the TUI repository:
```bash
cargo test localhost_devices_exchange_state_and_handoff
cargo test localhost_devices_sync_podcasts
cargo test devices::podcast_sync_tests
python scripts/test_device_interop.py ../furumusic
```
The first test uses real iroh streams, isolated SQLite databases, ownership
handoff, and a stalled peer. The podcast tests sync subscriptions, progress
and "start over" between TUI device stores (over iroh streams and through
the JSON messages), check a handoff with an episode and simulate a device
sync v3 peer with the exact JSON types of furumi-tui 0.3.x. The second builds both player test binaries and
exchanges their actual JSON messages over `127.0.0.1`: queue metadata,
bidirectional handoff, pause/seek and duplicate command fencing. It exercises
the TUI command adapter and web player hub, but does not start a browser or
PostgreSQL and does not cover web database migrations. Both tests use temporary
identities and data; no running player or user library is used.
## License
Furumi is released under the
[Do What The Fuck You Want To Public License, Version 2](LICENSE).
+40
View File
@@ -0,0 +1,40 @@
{ config, lib, pkgs, ... }:
let
sourceRoot = builtins.toString ./.;
sourceKey = builtins.substring 0 12 (builtins.hashString "sha256" sourceRoot);
transientDotfile = "/tmp/furumi-tui-devenv-${sourceKey}";
rustToolchain = builtins.fromTOML (builtins.readFile ./rust-toolchain.toml);
rustVersion = rustToolchain.toolchain.channel;
in
{
# Pure flakes only expose their read-only store source. Keep devenv's own
# task/profile state writable, then restore the real checkout path in-shell.
devenv.root = sourceRoot;
devenv.dotfile = transientDotfile;
devenv.state = "${transientDotfile}/state";
languages.rust = {
enable = true;
toolchainFile = ./rust-toolchain.toml;
};
packages = [
pkgs.pkg-config
] ++ pkgs.lib.optionals pkgs.stdenv.isLinux [
pkgs.alsa-lib
];
env.RUST_BACKTRACE = "1";
enterShell = lib.mkAfter ''
export DEVENV_ROOT="$PWD"
# Keep Nix builds separate from artifacts produced by rustup or another
# devenv generation. Cargo metadata is not compatible across compilers.
export CARGO_TARGET_DIR="$PWD/target/devenv-rust-${rustVersion}"
export PATH="${config.languages.rust.toolchainPackage}/bin:$PATH"
export RUSTC="${config.languages.rust.toolchainPackage}/bin/rustc"
export RUSTDOC="${config.languages.rust.toolchainPackage}/bin/rustdoc"
hash -r
'';
}
Generated
+399
View File
@@ -0,0 +1,399 @@
{
"nodes": {
"cachix": {
"inputs": {
"devenv": [
"devenv"
],
"flake-compat": [
"devenv",
"flake-compat"
],
"git-hooks": [
"devenv",
"git-hooks"
],
"nixpkgs": "nixpkgs"
},
"locked": {
"lastModified": 1777487137,
"narHash": "sha256-TuvKVBX60mqyMT6OB5JqVEh1YIWtFMR/igLCaCdC9tw=",
"owner": "cachix",
"repo": "cachix",
"rev": "a66a440c321d35f7193472c317f42a55ccd1cb93",
"type": "github"
},
"original": {
"owner": "cachix",
"ref": "latest",
"repo": "cachix",
"type": "github"
}
},
"crate2nix": {
"flake": false,
"locked": {
"lastModified": 1772186516,
"narHash": "sha256-8s28pzmQ6TOIUzznwFibtW1CMieMUl1rYJIxoQYor58=",
"owner": "rossng",
"repo": "crate2nix",
"rev": "ba5dd398e31ee422fbe021767eb83b0650303a6e",
"type": "github"
},
"original": {
"owner": "rossng",
"repo": "crate2nix",
"rev": "ba5dd398e31ee422fbe021767eb83b0650303a6e",
"type": "github"
}
},
"devenv": {
"inputs": {
"cachix": "cachix",
"crate2nix": "crate2nix",
"flake-compat": "flake-compat",
"flake-parts": "flake-parts",
"ghostty": "ghostty",
"git-hooks": "git-hooks",
"nix": "nix",
"nixd": "nixd",
"nixpkgs": [
"nixpkgs"
],
"rust-overlay": "rust-overlay"
},
"locked": {
"lastModified": 1785616853,
"narHash": "sha256-WKA53CfbSwXh/QuGHc3gsWoLNHYaKw4xgvkc9ceRgUA=",
"owner": "cachix",
"repo": "devenv",
"rev": "a3feed9ca96c66548496e8af2804d2a3a045d22e",
"type": "github"
},
"original": {
"owner": "cachix",
"repo": "devenv",
"type": "github"
}
},
"flake-compat": {
"flake": false,
"locked": {
"lastModified": 1767039857,
"narHash": "sha256-vNpUSpF5Nuw8xvDLj2KCwwksIbjua2LZCqhV1LNRDns=",
"owner": "edolstra",
"repo": "flake-compat",
"rev": "5edf11c44bc78a0d334f6334cdaf7d60d732daab",
"type": "github"
},
"original": {
"owner": "edolstra",
"repo": "flake-compat",
"type": "github"
}
},
"flake-parts": {
"inputs": {
"nixpkgs-lib": [
"devenv",
"nixpkgs"
]
},
"locked": {
"lastModified": 1778716662,
"narHash": "sha256-m1Yf0wZ8j1OHjTc2UwHwyQRSnNeSgLJOd7q5Y45hzi4=",
"owner": "hercules-ci",
"repo": "flake-parts",
"rev": "f7c1a2d347e4c52d5fb8d10cb4d94b5884e546fb",
"type": "github"
},
"original": {
"owner": "hercules-ci",
"repo": "flake-parts",
"type": "github"
}
},
"flake-parts_2": {
"inputs": {
"nixpkgs-lib": "nixpkgs-lib"
},
"locked": {
"lastModified": 1782949081,
"narHash": "sha256-vp6Y/Grm98ESt6ceOkWiHWyZRDV3J1RID4w+6NWK9yA=",
"owner": "hercules-ci",
"repo": "flake-parts",
"rev": "17c9d6cdfc60c64f4ee8d306f9bc0b4ccb51481e",
"type": "github"
},
"original": {
"owner": "hercules-ci",
"repo": "flake-parts",
"type": "github"
}
},
"ghostty": {
"flake": false,
"locked": {
"lastModified": 1784602798,
"narHash": "sha256-298x90knBUWX5GHGXh2SKsAKvStjU2ri9UgOGoF79/8=",
"owner": "ghostty-org",
"repo": "ghostty",
"rev": "88b4cd047fa627cdca6781bc7e7dc8b75a2cecb9",
"type": "github"
},
"original": {
"owner": "ghostty-org",
"repo": "ghostty",
"type": "github"
}
},
"git-hooks": {
"inputs": {
"flake-compat": [
"devenv",
"flake-compat"
],
"nixpkgs": [
"devenv",
"nixpkgs"
]
},
"locked": {
"lastModified": 1782908218,
"narHash": "sha256-wLMOrPgVyeF3XmP+qfYcLqnVdTxikdcSvbIY7rA9jTA=",
"owner": "cachix",
"repo": "git-hooks.nix",
"rev": "9f7e99119ece7705299595299f3b031f39356de1",
"type": "github"
},
"original": {
"owner": "cachix",
"repo": "git-hooks.nix",
"type": "github"
}
},
"mk-shell-bin": {
"locked": {
"lastModified": 1677004959,
"narHash": "sha256-/uEkr1UkJrh11vD02aqufCxtbF5YnhRTIKlx5kyvf+I=",
"owner": "rrbutani",
"repo": "nix-mk-shell-bin",
"rev": "ff5d8bd4d68a347be5042e2f16caee391cd75887",
"type": "github"
},
"original": {
"owner": "rrbutani",
"repo": "nix-mk-shell-bin",
"type": "github"
}
},
"nix": {
"inputs": {
"flake-compat": [
"devenv",
"flake-compat"
],
"flake-parts": [
"devenv",
"flake-parts"
],
"git-hooks-nix": [
"devenv",
"git-hooks"
],
"nixpkgs": [
"devenv",
"nixpkgs"
],
"nixpkgs-23-11": [
"devenv"
],
"nixpkgs-regression": [
"devenv"
]
},
"locked": {
"lastModified": 1785349663,
"narHash": "sha256-JSD8lPe5kalvPKx5X+inX8ZZdGLeXkAbd3Jiv7UDf+I=",
"owner": "cachix",
"repo": "nix",
"rev": "f33db89fd6db6edc337d93212f6628ab6d25f407",
"type": "github"
},
"original": {
"owner": "cachix",
"ref": "devenv-2.34",
"repo": "nix",
"type": "github"
}
},
"nix2container": {
"inputs": {
"nixpkgs": [
"nixpkgs"
]
},
"locked": {
"lastModified": 1775487831,
"narHash": "sha256-2lguQpLPQaxpQCJjXhmEEAfabwsAhkP29Z7fgLzHARA=",
"owner": "nlewo",
"repo": "nix2container",
"rev": "76be9608a7f4d6c985d28b0e7be903ae2547df3e",
"type": "github"
},
"original": {
"owner": "nlewo",
"repo": "nix2container",
"type": "github"
}
},
"nixd": {
"inputs": {
"flake-parts": [
"devenv",
"flake-parts"
],
"nixpkgs": [
"devenv",
"nixpkgs"
],
"treefmt-nix": "treefmt-nix"
},
"locked": {
"lastModified": 1783935112,
"narHash": "sha256-IAQ14nteIKXAz4cd75UcZrsHGEVJ7QNrkUwX9rmeZ/Y=",
"owner": "nix-community",
"repo": "nixd",
"rev": "a64cd33e53b316b6b092ea0a966640cd2309bf3d",
"type": "github"
},
"original": {
"owner": "nix-community",
"repo": "nixd",
"type": "github"
}
},
"nixpkgs": {
"locked": {
"lastModified": 1772624091,
"narHash": "sha256-QKyJ0QGWBn6r0invrMAK8dmJoBYWoOWy7lN+UHzW1jc=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "80bdc1e5ce51f56b19791b52b2901187931f5353",
"type": "github"
},
"original": {
"owner": "NixOS",
"ref": "nixos-unstable",
"repo": "nixpkgs",
"type": "github"
}
},
"nixpkgs-lib": {
"locked": {
"lastModified": 1782614948,
"narHash": "sha256-ePjCwr1sNm9NYUqywL7QfK3JnlS015msC+eBu2zKlp8=",
"owner": "nix-community",
"repo": "nixpkgs.lib",
"rev": "db3f255737b94216eb71cce308e2912cf6bc2d7c",
"type": "github"
},
"original": {
"owner": "nix-community",
"repo": "nixpkgs.lib",
"type": "github"
}
},
"nixpkgs_2": {
"locked": {
"lastModified": 1785571196,
"narHash": "sha256-KoTsyMQqnXQZq8deCEnu4QkyldkwH/bpMMhUcfMdGIw=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "148bab9c1c3c53136ecb44a6ea356a0ed5b39b06",
"type": "github"
},
"original": {
"owner": "NixOS",
"ref": "nixos-unstable",
"repo": "nixpkgs",
"type": "github"
}
},
"root": {
"inputs": {
"devenv": "devenv",
"flake-parts": "flake-parts_2",
"mk-shell-bin": "mk-shell-bin",
"nix2container": "nix2container",
"nixpkgs": "nixpkgs_2",
"rust-overlay": "rust-overlay_2"
}
},
"rust-overlay": {
"inputs": {
"nixpkgs": [
"devenv",
"nixpkgs"
]
},
"locked": {
"lastModified": 1782875958,
"narHash": "sha256-5eqDcnBjb1424HRQdnhuhNOBZguq1Z2tqSa2OMF/m2c=",
"owner": "oxalica",
"repo": "rust-overlay",
"rev": "13139aefa973f3d96c60c0fbab801de058ae25ca",
"type": "github"
},
"original": {
"owner": "oxalica",
"repo": "rust-overlay",
"type": "github"
}
},
"rust-overlay_2": {
"inputs": {
"nixpkgs": [
"nixpkgs"
]
},
"locked": {
"lastModified": 1785562362,
"narHash": "sha256-J15aBa3d6B1SUUAQydQ06wFjPzrrcVceb6jkdfwfGls=",
"owner": "oxalica",
"repo": "rust-overlay",
"rev": "5f29c219a7655519f8a9f8c6968064b82c17cc93",
"type": "github"
},
"original": {
"owner": "oxalica",
"repo": "rust-overlay",
"type": "github"
}
},
"treefmt-nix": {
"inputs": {
"nixpkgs": [
"devenv",
"nixd",
"nixpkgs"
]
},
"locked": {
"lastModified": 1780220602,
"narHash": "sha256-eynAfOmbmxJnkp7YewvCEbShNnnYJ9gLLqkzsYtBPeM=",
"owner": "numtide",
"repo": "treefmt-nix",
"rev": "db947814a175b7ca6ded66e21383d938df01c227",
"type": "github"
},
"original": {
"owner": "numtide",
"repo": "treefmt-nix",
"type": "github"
}
}
},
"root": "root",
"version": 7
}
+33
View File
@@ -0,0 +1,33 @@
{
description = "Furumi TUI development environment";
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
flake-parts.url = "github:hercules-ci/flake-parts";
devenv.url = "github:cachix/devenv";
devenv.inputs.nixpkgs.follows = "nixpkgs";
rust-overlay.url = "github:oxalica/rust-overlay";
rust-overlay.inputs.nixpkgs.follows = "nixpkgs";
nix2container.url = "github:nlewo/nix2container";
nix2container.inputs.nixpkgs.follows = "nixpkgs";
mk-shell-bin.url = "github:rrbutani/nix-mk-shell-bin";
};
outputs = inputs@{ flake-parts, ... }:
flake-parts.lib.mkFlake { inherit inputs; } {
systems = [
"x86_64-linux"
"aarch64-linux"
"x86_64-darwin"
"aarch64-darwin"
];
imports = [ inputs.devenv.flakeModule ];
perSystem = { ... }: {
devenv.shells.default = {
imports = [ ./devenv.nix ];
};
};
};
}
BIN
View File
Binary file not shown.

Before

Width:  |  Height:  |  Size: 104 KiB

After

Width:  |  Height:  |  Size: 118 KiB

+4
View File
@@ -0,0 +1,4 @@
[toolchain]
channel = "stable"
profile = "minimal"
components = ["clippy", "rust-src", "rustfmt"]
+65
View File
@@ -0,0 +1,65 @@
"""Build and run the real TUI and web protocol adapters against each other.
Usage: python scripts/test_device_interop.py [path/to/furumusic]
No user databases, accounts, audio outputs, or external servers are used.
"""
import json
import os
from pathlib import Path
import subprocess
import sys
import tempfile
def test_binary(repo):
result = subprocess.run(
["cargo", "test", "--locked", "--no-run", "--message-format=json"],
cwd=repo, text=True, encoding="utf-8", stdout=subprocess.PIPE,
)
result.check_returncode()
binaries = []
for line in result.stdout.splitlines():
event = json.loads(line)
if event.get("reason") == "compiler-artifact" and event.get("profile", {}).get("test") and event.get("executable"):
binaries.append(event["executable"])
if len(binaries) != 1:
raise RuntimeError(f"Expected one player test binary in {repo}, found {binaries}")
return binaries[0]
def main():
tui = Path(__file__).resolve().parents[1]
web = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else tui.parent / "furumusic"
tui_bin, web_bin = test_binary(tui), test_binary(web)
with tempfile.TemporaryDirectory(prefix="furumi-interop-") as directory:
env = dict(os.environ, FURUMI_INTEROP_DIR=directory)
processes = []
try:
for binary, test in [(web_bin, "federation::devices::interop_tests::localhost_tui_peer"),
(tui_bin, "devices::interop_tests::localhost_web_peer")]:
listing = subprocess.check_output([binary, "--list"], text=True, encoding="utf-8")
if f"{test}: test" not in listing:
raise RuntimeError(f"Required test {test} is missing from {binary}")
processes.append(subprocess.Popen(
[binary, "--ignored", "--exact", test, "--nocapture"], env=env,
stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
text=True, encoding="utf-8",
creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
))
codes = []
for process in processes:
output, _ = process.communicate(timeout=45)
print(output, end="")
codes.append(process.returncode)
if any(codes):
raise RuntimeError(f"Cross-player test failed: exit codes {codes}")
finally:
for process in processes:
if process.poll() is None:
process.kill()
process.wait()
print("PASS: TUI <-> WEB state, bidirectional handoff, pause/seek, duplicate fencing")
if __name__ == "__main__":
main()
-274
View File
@@ -1,274 +0,0 @@
use std::fs;
use std::io::ErrorKind;
use std::path::PathBuf;
use std::time::{SystemTime, UNIX_EPOCH};
use anyhow::{Context as _, Result, bail};
use serde::{Deserialize, Serialize};
use super::models::{TokensResponse, User};
/// Margin before access-token expiry at which we refresh proactively,
/// mirroring the Android/macOS clients.
pub const EXPIRY_SKEW_SECONDS: i64 = 60;
/// Persisted session, same shape as the macOS client's AuthSession.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AuthSession {
pub server_base_url: String,
pub user: User,
pub access_token: String,
pub refresh_token: String,
pub token_type: String,
pub expires_at_epoch_seconds: i64,
}
impl AuthSession {
pub fn new(server_base_url: String, user: User, tokens: TokensResponse) -> Self {
Self {
server_base_url,
user,
access_token: tokens.access_token,
refresh_token: tokens.refresh_token,
token_type: tokens.token_type,
expires_at_epoch_seconds: now_epoch_seconds() + tokens.expires_in_seconds,
}
}
pub fn apply_tokens(&mut self, tokens: TokensResponse) {
self.access_token = tokens.access_token;
self.refresh_token = tokens.refresh_token;
self.token_type = tokens.token_type;
self.expires_at_epoch_seconds = now_epoch_seconds() + tokens.expires_in_seconds;
}
pub fn access_token_expired(&self) -> bool {
now_epoch_seconds() + EXPIRY_SKEW_SECONDS >= self.expires_at_epoch_seconds
}
pub fn seconds_until_access_expiry(&self) -> i64 {
self.expires_at_epoch_seconds - now_epoch_seconds()
}
}
pub fn now_epoch_seconds() -> i64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_secs() as i64)
.unwrap_or(0)
}
pub fn session_path() -> Option<PathBuf> {
crate::config::project_dirs().map(|dirs| dirs.config_dir().join("credentials.json"))
}
pub fn load_session() -> Option<AuthSession> {
let Some(path) = session_path() else {
tracing::warn!("cannot determine config directory; no stored auth session loaded");
return None;
};
let text = match fs::read_to_string(&path) {
Ok(text) => text,
Err(err) if err.kind() == ErrorKind::NotFound => {
tracing::debug!(path = %path.display(), "credentials file not found");
return None;
}
Err(err) => {
tracing::warn!(path = %path.display(), %err, "failed to read credentials file");
return None;
}
};
match serde_json::from_str::<AuthSession>(&text) {
Ok(session) => {
tracing::info!(
path = %path.display(),
user_id = session.user.id,
user = %session.user.name,
server = %session.server_base_url,
expires_at_epoch_seconds = session.expires_at_epoch_seconds,
seconds_until_expiry = session.seconds_until_access_expiry(),
"loaded stored auth session"
);
Some(session)
}
Err(err) => {
tracing::warn!(path = %path.display(), %err, "ignoring unreadable credentials file");
None
}
}
}
pub fn save_session(session: &AuthSession) -> Result<()> {
let path = session_path().context("cannot determine config directory")?;
if let Some(parent) = path.parent() {
fs::create_dir_all(parent).with_context(|| format!("creating {}", parent.display()))?;
}
let text = serde_json::to_string_pretty(session)?;
tracing::info!(
path = %path.display(),
user_id = session.user.id,
user = %session.user.name,
server = %session.server_base_url,
expires_at_epoch_seconds = session.expires_at_epoch_seconds,
seconds_until_expiry = session.seconds_until_access_expiry(),
"persisting auth session"
);
write_private(&path, &text).with_context(|| format!("writing {}", path.display()))?;
tracing::debug!(path = %path.display(), "auth session persisted");
Ok(())
}
pub fn delete_session() {
if let Some(path) = session_path() {
match fs::remove_file(&path) {
Ok(()) => tracing::info!(path = %path.display(), "deleted stored auth session"),
Err(err) if err.kind() == ErrorKind::NotFound => {
tracing::debug!(path = %path.display(), "stored auth session already absent");
}
Err(err) => {
tracing::warn!(path = %path.display(), %err, "failed to delete stored auth session")
}
}
}
}
#[cfg(unix)]
fn write_private(path: &PathBuf, text: &str) -> std::io::Result<()> {
use std::io::Write as _;
use std::os::unix::fs::OpenOptionsExt as _;
let mut file = fs::OpenOptions::new()
.create(true)
.write(true)
.truncate(true)
.mode(0o600)
.open(path)?;
file.write_all(text.as_bytes())
}
#[cfg(not(unix))]
fn write_private(path: &PathBuf, text: &str) -> std::io::Result<()> {
fs::write(path, text)
}
/// Same normalization rules as the Android client's ServerConfig:
/// add https:// when no scheme, require http(s) with a host, reject
/// credentials/query/fragment, lowercase the host, trim trailing slashes.
pub fn normalize_base_url(raw: &str) -> Result<String> {
let trimmed = raw.trim().trim_end_matches('/');
if trimmed.is_empty() {
bail!("server URL is empty");
}
let with_scheme = if trimmed.contains("://") {
trimmed.to_string()
} else {
format!("https://{trimmed}")
};
let url = reqwest::Url::parse(&with_scheme).context("invalid server URL")?;
if !matches!(url.scheme(), "http" | "https") {
bail!("server URL must use http or https");
}
let host = url.host_str().filter(|h| !h.is_empty());
let Some(host) = host else {
bail!("server URL has no host");
};
if !url.username().is_empty() || url.password().is_some() {
bail!("server URL must not contain credentials");
}
if url.query().is_some() || url.fragment().is_some() {
bail!("server URL must not contain a query or fragment");
}
let mut normalized = format!("{}://{}", url.scheme(), host.to_ascii_lowercase());
if let Some(port) = url.port() {
normalized.push_str(&format!(":{port}"));
}
let path = url.path().trim_end_matches('/');
normalized.push_str(path);
Ok(normalized)
}
/// Accepts what the user pastes after browser SSO: either the full
/// `furumi://auth/callback?code=furu_mx_...` link (copied from the
/// "Open Furumi" button) or the bare `furu_mx_...` code.
pub fn extract_sso_code(input: &str) -> Result<String> {
let input = input.trim();
if input.is_empty() {
bail!("paste the link or code first");
}
if input.starts_with("furu_mx_") {
return Ok(input.to_string());
}
if let Ok(url) = reqwest::Url::parse(input) {
if let Some((_, error)) = url.query_pairs().find(|(k, _)| k == "error") {
bail!("SSO failed: {error}");
}
if let Some((_, code)) = url.query_pairs().find(|(k, _)| k == "code") {
return Ok(code.into_owned());
}
}
bail!("no furu_mx_ code found in the pasted text");
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn normalize_adds_https_and_strips_slash() {
assert_eq!(
normalize_base_url(" Music.Hexor.cy/ ").unwrap(),
"https://music.hexor.cy"
);
}
#[test]
fn normalize_keeps_port_and_path() {
assert_eq!(
normalize_base_url("http://localhost:8000/furumi/").unwrap(),
"http://localhost:8000/furumi"
);
}
#[test]
fn normalize_rejects_bad_urls() {
assert!(normalize_base_url("").is_err());
assert!(normalize_base_url("ftp://x").is_err());
assert!(normalize_base_url("https://user:pw@host").is_err());
assert!(normalize_base_url("https://host?x=1").is_err());
}
#[test]
fn sso_code_from_deep_link() {
let code = extract_sso_code("furumi://auth/callback?code=furu_mx_abc123").unwrap();
assert_eq!(code, "furu_mx_abc123");
}
#[test]
fn sso_code_bare() {
assert_eq!(extract_sso_code(" furu_mx_x ").unwrap(), "furu_mx_x");
}
#[test]
fn sso_error_is_reported() {
let err = extract_sso_code("furumi://auth/callback?error=provider_denied")
.unwrap_err()
.to_string();
assert!(err.contains("provider_denied"));
}
#[test]
fn expiry_uses_skew() {
let session = AuthSession {
server_base_url: "https://x".into(),
user: User {
id: 1,
name: "n".into(),
role: "user".into(),
},
access_token: "a".into(),
refresh_token: "r".into(),
token_type: "Bearer".into(),
expires_at_epoch_seconds: now_epoch_seconds() + 30,
};
assert!(session.access_token_expired());
}
}
-778
View File
@@ -1,778 +0,0 @@
use serde::Serialize;
use serde::de::DeserializeOwned;
use tokio::sync::Mutex;
use super::auth::{self, AuthSession};
use super::models::{
ApiErrorBody, ArtistDetail, ArtistsPage, DevicePlaybackState, DevicePollResponse,
LikesResponse, LoginResponse, MeResponse, PlaylistCard, PlaylistDetail, ReleaseDetail,
SearchResults, TokensResponse, TrackItem,
};
#[derive(Debug, thiserror::Error)]
pub enum ApiError {
#[error("{0}")]
Server(String),
/// Refresh token rejected or expired — the user must sign in again.
#[error("session expired, please sign in again")]
SessionExpired,
#[error("network error: {0}")]
Network(#[from] reqwest::Error),
#[error("{0}")]
Other(#[from] anyhow::Error),
}
pub fn http_client() -> reqwest::Client {
reqwest::Client::builder()
.user_agent(format!(
"furumi-tui/{} ({})",
env!("CARGO_PKG_VERSION"),
std::env::consts::OS
))
.connect_timeout(std::time::Duration::from_secs(10))
.timeout(std::time::Duration::from_secs(30))
.build()
.expect("reqwest client config is static")
}
pub fn device_name() -> String {
format!("furumi-tui ({})", std::env::consts::OS)
}
pub fn device_user_agent() -> String {
format!(
"FurumiTUI/{} {}",
env!("CARGO_PKG_VERSION"),
std::env::consts::OS
)
}
#[derive(Serialize)]
struct PasswordLoginRequest<'a> {
username: &'a str,
password: &'a str,
device_name: String,
}
#[derive(Serialize)]
struct SsoExchangeRequest<'a> {
code: &'a str,
device_name: String,
}
#[derive(Serialize)]
struct RefreshRequest<'a> {
refresh_token: &'a str,
}
#[derive(Serialize)]
struct LogoutRequest<'a> {
refresh_token: &'a str,
}
pub async fn login_password(
http: &reqwest::Client,
base_url: &str,
username: &str,
password: &str,
) -> Result<AuthSession, ApiError> {
let device_name = device_name();
tracing::info!(%base_url, %device_name, "password login request started");
let response = match http
.post(format!("{base_url}/api/auth/password"))
.json(&PasswordLoginRequest {
username,
password,
device_name,
})
.send()
.await
{
Ok(response) => response,
Err(err) => {
tracing::warn!(%base_url, %err, "password login request failed");
return Err(ApiError::Network(err));
}
};
let status = response.status();
let login: LoginResponse = match parse_response(response).await {
Ok(login) => login,
Err(err) => {
tracing::warn!(%base_url, %status, %err, "password login rejected");
return Err(err);
}
};
let session = AuthSession::new(base_url.to_string(), login.user, login.tokens);
tracing::info!(
%base_url,
user_id = session.user.id,
user = %session.user.name,
expires_at_epoch_seconds = session.expires_at_epoch_seconds,
seconds_until_expiry = session.seconds_until_access_expiry(),
"password login succeeded"
);
Ok(session)
}
pub async fn login_sso_exchange(
http: &reqwest::Client,
base_url: &str,
code: &str,
) -> Result<AuthSession, ApiError> {
let device_name = device_name();
tracing::info!(%base_url, %device_name, "SSO exchange request started");
let response = match http
.post(format!("{base_url}/api/auth/sso/exchange"))
.json(&SsoExchangeRequest { code, device_name })
.send()
.await
{
Ok(response) => response,
Err(err) => {
tracing::warn!(%base_url, %err, "SSO exchange request failed");
return Err(ApiError::Network(err));
}
};
let status = response.status();
let login: LoginResponse = match parse_response(response).await {
Ok(login) => login,
Err(err) => {
tracing::warn!(%base_url, %status, %err, "SSO exchange rejected");
return Err(err);
}
};
let session = AuthSession::new(base_url.to_string(), login.user, login.tokens);
tracing::info!(
%base_url,
user_id = session.user.id,
user = %session.user.name,
expires_at_epoch_seconds = session.expires_at_epoch_seconds,
seconds_until_expiry = session.seconds_until_access_expiry(),
"SSO exchange succeeded"
);
Ok(session)
}
/// Browser entry point for SSO. redirect_uri is either our loopback
/// listener (`http://127.0.0.1:{port}/callback`) or the `furumi://` deep
/// link as a manual-paste fallback.
pub fn sso_start_url(base_url: &str, redirect_uri: &str) -> String {
let mut url = reqwest::Url::parse(&format!("{base_url}/auth/mobile/oidc/start"))
.expect("base_url is pre-validated");
url.query_pairs_mut()
.append_pair("redirect_uri", redirect_uri);
url.to_string()
}
async fn refresh_tokens(
http: &reqwest::Client,
base_url: &str,
refresh_token: &str,
) -> Result<TokensResponse, ApiError> {
tracing::info!(%base_url, "refresh token request started");
let response = match http
.post(format!("{base_url}/api/auth/refresh"))
.json(&RefreshRequest { refresh_token })
.send()
.await
{
Ok(response) => response,
Err(err) => {
tracing::warn!(%base_url, %err, "refresh token request failed");
return Err(ApiError::Network(err));
}
};
let status = response.status();
if response.status() == reqwest::StatusCode::UNAUTHORIZED {
tracing::warn!(%base_url, %status, "refresh token rejected by server");
return Err(ApiError::SessionExpired);
}
let tokens: TokensResponse = match parse_response(response).await {
Ok(tokens) => tokens,
Err(err) => {
tracing::warn!(%base_url, %status, %err, "refresh token request returned error");
return Err(err);
}
};
tracing::info!(
%base_url,
%status,
expires_in_seconds = tokens.expires_in_seconds,
"refresh token request succeeded"
);
Ok(tokens)
}
/// Mirrors the backend's PlaybackStateDto.
#[derive(Debug, Serialize)]
pub struct PlaybackStateBody {
pub current_track_id: Option<i64>,
pub position_ms: i32,
pub queue: Vec<i64>,
pub queue_position: i32,
pub shuffle: bool,
pub repeat_mode: String,
pub volume: f64,
}
#[derive(Serialize)]
struct DevicePollRequest<'a> {
device_id: &'a str,
user_agent: String,
current_jam_id: Option<&'a str>,
playback_state: Option<DevicePlaybackState>,
}
#[derive(Serialize)]
struct DeviceActiveRequest<'a> {
device_id: &'a str,
current_device_id: &'a str,
}
#[derive(Serialize)]
struct DeviceCommandRequest<'a> {
target_device_id: Option<&'a str>,
jam_id: Option<&'a str>,
command: &'a str,
payload: &'a serde_json::Value,
}
/// Percent-encode a query-string value.
fn url_encode(value: &str) -> String {
let mut out = String::with_capacity(value.len());
for byte in value.bytes() {
match byte {
b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
out.push(byte as char);
}
_ => out.push_str(&format!("%{byte:02X}")),
}
}
out
}
async fn parse_response<T: DeserializeOwned>(response: reqwest::Response) -> Result<T, ApiError> {
let status = response.status();
if status.is_success() {
return Ok(response.json().await?);
}
let message = match response.json::<ApiErrorBody>().await {
Ok(body) => body.error,
Err(_) => format!("server returned {status}"),
};
Err(ApiError::Server(message))
}
fn stream_error_is_auth_related(err: &ApiError) -> bool {
let ApiError::Server(message) = err else {
return false;
};
let message = message.to_ascii_lowercase();
message.contains("401")
|| message.contains("unauthorized")
|| message.contains("authentication")
}
/// Authenticated API client. Owns the session; refreshes the access token
/// proactively (60s skew) and once more on 401, persisting rotated tokens.
/// The session mutex makes concurrent refreshes single-flight.
pub struct ApiClient {
http: reqwest::Client,
base_url: String,
session: Mutex<AuthSession>,
}
impl ApiClient {
pub fn new(http: reqwest::Client, session: AuthSession) -> Self {
Self {
http,
base_url: session.server_base_url.clone(),
session: Mutex::new(session),
}
}
pub fn base_url(&self) -> &str {
&self.base_url
}
pub async fn me(&self) -> Result<MeResponse, ApiError> {
self.get_json("/api/player/me").await
}
pub async fn artists(&self, page: i64, limit: i64) -> Result<ArtistsPage, ApiError> {
self.get_json(&format!("/api/player/artists?page={page}&limit={limit}"))
.await
}
pub async fn artist(&self, id: i64) -> Result<ArtistDetail, ApiError> {
self.get_json(&format!("/api/player/artists/{id}")).await
}
pub async fn release(&self, id: i64) -> Result<ReleaseDetail, ApiError> {
self.get_json(&format!("/api/player/releases/{id}")).await
}
pub async fn search(&self, query: &str, limit: i64) -> Result<SearchResults, ApiError> {
self.get_json(&format!(
"/api/player/search?q={}&limit={limit}",
url_encode(query)
))
.await
}
/// Open an audio stream for playback: background download backed by a
/// temp file, exposing blocking Read+Seek for the decoder; seeking into
/// not-yet-downloaded ranges uses HTTP Range requests.
///
/// The download client carries the bearer token valid at start; on very
/// long tracks a Range request after token expiry (15 min) can fail —
/// acceptable for now, a refreshing middleware can replace this later.
pub async fn open_stream(
&self,
path: &str,
) -> Result<(crate::player::TrackReader, Option<u64>), ApiError> {
let url: reqwest::Url = format!("{}{path}", self.base_url)
.parse()
.map_err(|err| ApiError::Server(format!("bad stream url: {err}")))?;
tracing::info!(path, "opening authenticated stream");
let token = self.fresh_access_token().await?;
match self.open_stream_with_token(url.clone(), &token).await {
Ok(stream) => {
tracing::debug!(path, "authenticated stream opened");
Ok(stream)
}
Err(err) if stream_error_is_auth_related(&err) => {
tracing::warn!(path, %err, "stream rejected bearer token; refreshing and retrying");
let retry_token = self.refresh_after_rejection(&token).await?;
let result = self.open_stream_with_token(url, &retry_token).await;
if let Err(retry_err) = &result {
tracing::warn!(path, %retry_err, "stream open failed after auth refresh");
}
result
}
Err(err) => {
tracing::warn!(path, %err, "stream open failed");
Err(err)
}
}
}
async fn open_stream_with_token(
&self,
url: reqwest::Url,
token: &str,
) -> Result<(crate::player::TrackReader, Option<u64>), ApiError> {
use stream_download::Settings;
use stream_download::http::HttpStream;
use stream_download::source::SourceStream as _;
use stream_download::storage::temp::TempStorageProvider;
let mut headers = reqwest::header::HeaderMap::new();
let value = format!("Bearer {token}")
.parse()
.map_err(|_| ApiError::Server("invalid token header".to_string()))?;
headers.insert(reqwest::header::AUTHORIZATION, value);
let client = reqwest::Client::builder()
.default_headers(headers)
.build()
.map_err(ApiError::Network)?;
let stream = HttpStream::new(client, url)
.await
.map_err(|err| ApiError::Server(format!("stream open failed: {err}")))?;
let byte_len = stream.content_length();
let reader = stream_download::StreamDownload::from_stream(
stream,
TempStorageProvider::new(),
Settings::default(),
)
.await
.map_err(|err| ApiError::Server(format!("stream start failed: {err}")))?;
Ok((reader, byte_len))
}
/// Raw bytes (cover art, artist images) from a server-relative path.
pub async fn get_bytes(&self, path: &str) -> Result<Vec<u8>, ApiError> {
let url = format!("{}{path}", self.base_url);
let response = self
.send_authed(&url, |client, url, token| {
client.get(url).bearer_auth(token)
})
.await?;
let status = response.status();
if !status.is_success() {
return Err(ApiError::Server(format!("server returned {status}")));
}
Ok(response.bytes().await?.to_vec())
}
pub async fn playlists(&self) -> Result<Vec<PlaylistCard>, ApiError> {
self.get_json("/api/player/playlists").await
}
pub async fn playlist(&self, id: i64) -> Result<PlaylistDetail, ApiError> {
self.get_json(&format!("/api/player/playlists/{id}")).await
}
pub async fn create_playlist(&self, title: &str) -> Result<PlaylistCard, ApiError> {
#[derive(Serialize)]
struct Body<'a> {
title: &'a str,
}
self.post_json("/api/player/playlists", &Body { title })
.await
}
pub async fn add_tracks_to_playlist(
&self,
playlist_id: i64,
track_ids: &[i64],
) -> Result<(), ApiError> {
#[derive(Serialize)]
struct Body<'a> {
track_ids: &'a [i64],
}
let _: serde_json::Value = self
.post_json(
&format!("/api/player/playlists/{playlist_id}/tracks"),
&Body { track_ids },
)
.await?;
Ok(())
}
pub async fn likes(&self) -> Result<Vec<i64>, ApiError> {
let response: LikesResponse = self.get_json("/api/player/likes").await?;
Ok(response.track_ids)
}
pub async fn toggle_like(&self, track_id: i64) -> Result<bool, ApiError> {
#[derive(serde::Deserialize)]
struct Body {
liked: bool,
}
let body: Body = self
.post_json(&format!("/api/player/likes/toggle/{track_id}"), &())
.await?;
Ok(body.liked)
}
#[allow(
dead_code,
reason = "device-sync state restore needs id→track resolution"
)]
pub async fn tracks_by_ids(&self, track_ids: &[i64]) -> Result<Vec<TrackItem>, ApiError> {
#[derive(Serialize)]
struct Body<'a> {
track_ids: &'a [i64],
}
self.post_json("/api/player/tracks-by-ids", &Body { track_ids })
.await
}
/// Tell last.fm (via the server) what is playing right now. Called at
/// track start; the completed-play scrobble goes through /history.
pub async fn lastfm_now_playing(&self, track_id: i64) -> Result<(), ApiError> {
#[derive(Serialize)]
struct Body {
track_id: i64,
}
let _: serde_json::Value = self
.post_json("/api/player/lastfm/now-playing", &Body { track_id })
.await?;
Ok(())
}
/// Report a finished/aborted listen to the play history.
/// Body shape is the backend's HistoryEntry; `completed` marks a full
/// play (vs a manual skip).
pub async fn report_history(
&self,
track_id: i64,
started_at: Option<i64>,
listened_seconds: i32,
completed: bool,
) -> Result<(), ApiError> {
#[derive(Serialize)]
struct Body {
track_id: i64,
started_at: Option<i64>,
duration_listened: Option<i32>,
completed: bool,
}
let _: serde_json::Value = self
.post_json(
"/api/player/history",
&Body {
track_id,
started_at,
duration_listened: Some(listened_seconds),
completed,
},
)
.await?;
Ok(())
}
/// Persist playback state server-side (used for cross-device restore).
pub async fn push_state(&self, state: &PlaybackStateBody) -> Result<(), ApiError> {
let _: serde_json::Value = self.put_json("/api/player/state", state).await?;
Ok(())
}
pub async fn poll_device(
&self,
device_id: &str,
playback_state: Option<DevicePlaybackState>,
) -> Result<DevicePollResponse, ApiError> {
self.post_json(
"/api/player/devices/poll",
&DevicePollRequest {
device_id,
user_agent: device_user_agent(),
current_jam_id: None,
playback_state,
},
)
.await
}
pub async fn select_device(
&self,
target_device_id: &str,
current_device_id: &str,
) -> Result<DevicePollResponse, ApiError> {
self.post_json(
"/api/player/devices/active",
&DeviceActiveRequest {
device_id: target_device_id,
current_device_id,
},
)
.await
}
pub async fn send_device_command(
&self,
target_device_id: Option<&str>,
command: &str,
payload: &serde_json::Value,
) -> Result<(), ApiError> {
let _: serde_json::Value = self
.post_json(
"/api/player/devices/command",
&DeviceCommandRequest {
target_device_id,
jam_id: None,
command,
payload,
},
)
.await?;
Ok(())
}
/// Revoke this device's session server-side. Best effort: local
/// credentials are deleted regardless of the outcome.
pub async fn logout(&self) -> Result<bool, ApiError> {
let (access_token, refresh_token) = {
let session = self.session.lock().await;
(session.access_token.clone(), session.refresh_token.clone())
};
tracing::info!(base_url = %self.base_url, "logout request started");
let response = self
.http
.post(format!("{}/api/auth/logout", self.base_url))
.bearer_auth(access_token)
.json(&LogoutRequest {
refresh_token: &refresh_token,
})
.send()
.await?;
let status = response.status();
#[derive(serde::Deserialize)]
struct LogoutResponse {
revoked: bool,
}
let body: LogoutResponse = match parse_response(response).await {
Ok(body) => body,
Err(err) => {
tracing::warn!(base_url = %self.base_url, %status, %err, "logout request failed");
return Err(err);
}
};
tracing::info!(base_url = %self.base_url, %status, revoked = body.revoked, "logout request succeeded");
Ok(body.revoked)
}
pub async fn get_json<T: DeserializeOwned>(&self, path: &str) -> Result<T, ApiError> {
self.json_request::<(), T>(reqwest::Method::GET, path, None)
.await
}
pub async fn post_json<B: Serialize, T: DeserializeOwned>(
&self,
path: &str,
body: &B,
) -> Result<T, ApiError> {
self.json_request(reqwest::Method::POST, path, Some(body))
.await
}
pub async fn put_json<B: Serialize, T: DeserializeOwned>(
&self,
path: &str,
body: &B,
) -> Result<T, ApiError> {
self.json_request(reqwest::Method::PUT, path, Some(body))
.await
}
async fn json_request<B: Serialize, T: DeserializeOwned>(
&self,
method: reqwest::Method,
path: &str,
body: Option<&B>,
) -> Result<T, ApiError> {
let url = format!("{}{path}", self.base_url);
let response = self
.send_authed(&url, |client, url, token| {
let mut request = client.request(method.clone(), url).bearer_auth(token);
if let Some(body) = body {
request = request.json(body);
}
request
})
.await;
let response = match response {
Ok(response) => response,
Err(err) => {
tracing::warn!(%err, %method, path, "api request failed");
return Err(err);
}
};
let status = response.status();
let result = parse_response(response).await;
if let Err(err) = &result {
tracing::warn!(%err, %status, %method, path, "api response error");
} else {
tracing::debug!(%status, %method, path, "api ok");
}
result
}
/// Send a request with a fresh bearer token; on 401, refresh once and
/// retry. `build` is called per attempt because RequestBuilder is not
/// reusable after send.
async fn send_authed<F>(&self, url: &str, build: F) -> Result<reqwest::Response, ApiError>
where
F: Fn(&reqwest::Client, &str, &str) -> reqwest::RequestBuilder,
{
let token = self.fresh_access_token().await?;
let response = build(&self.http, url, &token).send().await?;
if response.status() == reqwest::StatusCode::UNAUTHORIZED {
tracing::warn!(%url, "authenticated request returned 401; refreshing token and retrying");
let token = self.refresh_after_rejection(&token).await?;
let response = build(&self.http, url, &token).send().await?;
if response.status() == reqwest::StatusCode::UNAUTHORIZED {
tracing::warn!(%url, "authenticated request still returned 401 after token refresh");
}
return Ok(response);
}
Ok(response)
}
async fn fresh_access_token(&self) -> Result<String, ApiError> {
let mut session = self.session.lock().await;
let seconds_until_expiry = session.seconds_until_access_expiry();
if session.access_token_expired() {
tracing::info!(
user_id = session.user.id,
user = %session.user.name,
expires_at_epoch_seconds = session.expires_at_epoch_seconds,
seconds_until_expiry,
"access token expired or near expiry; refreshing"
);
self.refresh_locked(&mut session).await?;
}
Ok(session.access_token.clone())
}
/// A 401 with a token another task already rotated just retries with the
/// current token; otherwise this task performs the refresh itself.
async fn refresh_after_rejection(&self, rejected_token: &str) -> Result<String, ApiError> {
let mut session = self.session.lock().await;
if session.access_token != rejected_token {
tracing::info!(
user_id = session.user.id,
user = %session.user.name,
"rejected access token was already rotated by another task"
);
return Ok(session.access_token.clone());
}
tracing::warn!(
user_id = session.user.id,
user = %session.user.name,
seconds_until_expiry = session.seconds_until_access_expiry(),
"access token was rejected; refreshing"
);
self.refresh_locked(&mut session).await?;
Ok(session.access_token.clone())
}
async fn refresh_locked(&self, session: &mut AuthSession) -> Result<(), ApiError> {
let user_id = session.user.id;
let user = session.user.name.clone();
let previous_expires_at = session.expires_at_epoch_seconds;
let previous_seconds_until_expiry = session.seconds_until_access_expiry();
tracing::info!(
user_id,
user = %user,
server = %self.base_url,
previous_expires_at_epoch_seconds = previous_expires_at,
previous_seconds_until_expiry,
"refreshing access token"
);
let result = refresh_tokens(&self.http, &self.base_url, &session.refresh_token).await;
match result {
Ok(tokens) => {
let expires_in_seconds = tokens.expires_in_seconds;
session.apply_tokens(tokens);
if let Err(err) = auth::save_session(session) {
tracing::warn!(%err, "failed to persist rotated tokens");
}
tracing::info!(
user_id = session.user.id,
user = %session.user.name,
server = %self.base_url,
expires_in_seconds,
expires_at_epoch_seconds = session.expires_at_epoch_seconds,
seconds_until_expiry = session.seconds_until_access_expiry(),
"access token refreshed"
);
Ok(())
}
Err(ApiError::SessionExpired) => {
tracing::warn!(
user_id,
user = %user,
server = %self.base_url,
"refresh token expired or rejected; clearing stored session"
);
auth::delete_session();
Err(ApiError::SessionExpired)
}
Err(err) => {
tracing::warn!(
user_id,
user = %user,
server = %self.base_url,
%err,
"access token refresh failed"
);
Err(err)
}
}
}
}
-3
View File
@@ -1,3 +0,0 @@
pub mod auth;
pub mod client;
pub mod models;
-314
View File
@@ -1,314 +0,0 @@
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct User {
pub id: i64,
pub name: String,
pub role: String,
}
#[derive(Debug, Clone, Deserialize)]
pub struct TokensResponse {
pub access_token: String,
pub refresh_token: String,
pub token_type: String,
pub expires_in_seconds: i64,
}
#[derive(Debug, Deserialize)]
pub struct LoginResponse {
pub user: User,
pub tokens: TokensResponse,
}
#[derive(Debug, Deserialize)]
#[allow(
dead_code,
reason = "rendered by the profile view in a later milestone"
)]
pub struct MeStats {
pub liked_tracks: i64,
pub playlists: i64,
pub plays: i64,
pub listened_minutes: i64,
}
#[derive(Debug, Deserialize)]
#[allow(
dead_code,
reason = "rendered by the profile view in a later milestone"
)]
pub struct MeResponse {
pub id: i64,
pub name: String,
pub role: String,
pub stats: MeStats,
}
#[derive(Debug, Deserialize)]
pub struct ApiErrorBody {
pub error: String,
}
#[derive(Debug, Clone, Deserialize)]
pub struct ArtistCard {
#[allow(dead_code, reason = "opens the artist view in the next milestone")]
pub id: i64,
pub name: String,
/// Relative path like `/api/player/cover/{file_id}/medium`.
pub image_url: Option<String>,
pub release_count: i64,
pub track_count: i64,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ArtistRef {
#[allow(dead_code, reason = "navigation to artists from track rows later")]
pub id: i64,
pub name: String,
}
/// Serialize keeps every field the backend sent us, so device-sync payloads
/// (play_from_index, queue_add) carry full track objects like the web does.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TrackItem {
#[allow(dead_code, reason = "playback engine consumes this in milestone 3")]
pub id: i64,
pub title: String,
/// Absent in the artist-appearance variant of track payloads.
#[serde(default)]
pub track_number: Option<i32>,
#[serde(default)]
pub disc_number: Option<i32>,
pub duration_seconds: f64,
#[serde(default)]
pub artists: Vec<ArtistRef>,
#[serde(default)]
pub featured_artists: Vec<ArtistRef>,
#[allow(dead_code, reason = "jump-to-release navigation later")]
#[serde(default)]
pub release_id: i64,
#[serde(default)]
pub release_title: String,
#[allow(dead_code, reason = "shown in queue/now-playing later")]
pub release_year: Option<i32>,
/// Server-relative path to `/api/player/stream/{id}`.
#[serde(default)]
pub stream_url: String,
#[allow(dead_code, reason = "now-playing artwork in milestone 3")]
pub cover_url: Option<String>,
#[serde(default)]
pub uploader_name: String,
pub audio_format: Option<String>,
pub audio_bitrate: Option<i32>,
pub audio_sample_rate: Option<i32>,
pub audio_bit_depth: Option<i32>,
pub file_size_bytes: Option<i64>,
pub lastfm_listeners: Option<i64>,
#[allow(dead_code, reason = "popularity column later")]
pub lastfm_playcount: Option<i64>,
pub lastfm_rating: Option<f64>,
pub lastfm_updated_at: Option<String>,
}
impl TrackItem {
pub fn artist_line(&self) -> String {
let mut names: Vec<&str> = self.artists.iter().map(|a| a.name.as_str()).collect();
if !self.featured_artists.is_empty() {
names.push("feat.");
names.extend(self.featured_artists.iter().map(|a| a.name.as_str()));
}
names.join(", ")
}
pub fn duration_label(&self) -> String {
let total = self.duration_seconds.round() as i64;
format!("{}:{:02}", total / 60, total % 60)
}
/// Full tech line for the status bar, including the sample rate.
pub fn tech_label_full(&self) -> String {
let mut parts = Vec::new();
if let Some(format) = &self.audio_format {
parts.push(format.to_uppercase());
}
if let Some(bitrate) = self.audio_bitrate {
parts.push(format!("{bitrate}kbps"));
}
if let Some(rate) = self.audio_sample_rate {
parts.push(format!("{:.1}kHz", f64::from(rate) / 1000.0));
}
if let Some(bytes) = self.file_size_bytes {
parts.push(format!("{:.1}MB", bytes as f64 / 1_048_576.0));
}
parts.join(" · ")
}
}
#[derive(Debug, Clone, Deserialize)]
pub struct ReleaseCard {
pub id: i64,
pub title: String,
pub release_type: String,
pub year: Option<i32>,
pub cover_url: Option<String>,
pub track_count: i64,
}
#[derive(Debug, Deserialize)]
pub struct ArtistDetail {
#[allow(dead_code, reason = "cache key is held by the caller")]
pub id: i64,
pub name: String,
pub image_url: Option<String>,
pub total_track_count: i64,
pub total_play_count: i64,
pub top_tracks: Vec<TrackItem>,
pub releases: Vec<ReleaseCard>,
/// Tracks where this artist is featured (the only content for artists
/// without own releases).
#[serde(default)]
pub featured_tracks: Vec<TrackItem>,
}
#[derive(Debug, Clone, Deserialize)]
pub struct UploaderSummary {
pub name: String,
#[allow(dead_code, reason = "per-uploader stats for a later detail popup")]
pub track_count: i64,
}
#[derive(Debug, Deserialize)]
pub struct ReleaseDetail {
#[allow(dead_code, reason = "cache key is held by the caller")]
pub id: i64,
pub title: String,
pub release_type: String,
pub year: Option<i32>,
pub cover_url: Option<String>,
pub artists: Vec<ArtistRef>,
pub tracks: Vec<TrackItem>,
pub uploaders: Vec<UploaderSummary>,
}
#[derive(Debug, Clone, Deserialize)]
pub struct PlaylistCard {
pub id: i64,
pub title: String,
pub track_count: i64,
pub is_own: bool,
pub owner_name: Option<String>,
pub is_public: bool,
#[allow(dead_code, reason = "save/unsave playlists later")]
pub is_saved: bool,
#[allow(dead_code, reason = "playlist kinds get distinct icons later")]
pub kind: String,
}
#[derive(Debug, Deserialize)]
pub struct PlaylistDetail {
#[allow(dead_code, reason = "cache key is held by the caller")]
pub id: i64,
pub title: String,
#[allow(dead_code, reason = "shown in a detail header later")]
pub description: Option<String>,
pub tracks: Vec<TrackItem>,
}
#[derive(Debug, Deserialize)]
pub struct LikesResponse {
pub track_ids: Vec<i64>,
}
#[derive(Debug, Clone, Deserialize)]
pub struct DeviceDto {
pub id: String,
pub name: String,
pub kind: String,
#[allow(dead_code, reason = "server-side flag; we compare ids directly")]
pub is_current: bool,
pub is_active: bool,
#[allow(dead_code, reason = "freshness display later")]
pub last_seen_ms: i64,
}
#[derive(Debug, Deserialize)]
pub struct DeviceCommandDto {
#[allow(dead_code, reason = "commands are applied in poll order")]
pub id: Option<String>,
pub command: String,
#[serde(default)]
pub payload: serde_json::Value,
}
/// Mirrors the backend's PlayerDevicePlaybackStateDto; tracks stay raw JSON
/// so unknown fields survive the round trip between clients.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct DevicePlaybackState {
#[serde(default)]
pub track: Option<serde_json::Value>,
#[serde(default)]
pub tracks: Vec<serde_json::Value>,
#[serde(default)]
pub index: i32,
#[serde(default)]
pub position_seconds: f64,
#[serde(default)]
pub duration_seconds: f64,
#[serde(default)]
pub paused: bool,
#[serde(default)]
pub shuffle: bool,
#[serde(default = "default_repeat_mode")]
pub repeat_mode: String,
#[serde(default = "default_volume")]
pub volume: f64,
#[serde(default)]
pub updated_at_ms: i64,
}
fn default_repeat_mode() -> String {
"off".to_string()
}
fn default_volume() -> f64 {
1.0
}
#[derive(Debug, Deserialize)]
pub struct DevicePollResponse {
#[allow(dead_code, reason = "echo of our own id")]
pub device_id: String,
pub active_device_id: Option<String>,
#[serde(default)]
pub devices: Vec<DeviceDto>,
#[serde(default)]
pub commands: Vec<DeviceCommandDto>,
#[serde(default)]
#[allow(dead_code, reason = "Jam control is out of scope for the TUI v1")]
pub current_jam_id: Option<String>,
pub playback_state: Option<DevicePlaybackState>,
}
#[derive(Debug, Default, Deserialize)]
pub struct SearchResults {
pub artists: Vec<ArtistCard>,
pub releases: Vec<ReleaseCard>,
pub tracks: Vec<TrackItem>,
}
impl SearchResults {
pub fn len(&self) -> usize {
self.artists.len() + self.releases.len() + self.tracks.len()
}
}
#[derive(Debug, Deserialize)]
pub struct ArtistsPage {
pub items: Vec<ArtistCard>,
pub total: i64,
pub page: i64,
#[allow(dead_code, reason = "part of the server pagination envelope")]
pub per_page: i64,
pub has_more: bool,
}
+99 -15
View File
@@ -21,28 +21,63 @@ pub enum Action {
PlayPause,
NextTrack,
PrevTrack,
SeekForward { seconds: u32 },
SeekBackward { seconds: u32 },
SeekForward {
seconds: u32,
},
SeekBackward {
seconds: u32,
},
VolumeUp,
VolumeDown,
ToggleShuffle,
CycleRepeat,
ToggleVisualizer,
ToggleLike,
ToggleTrackSelection,
OpenTrackInfo,
OpenCurrentTrackInfo,
QueueAddNext,
QueueAddLast,
MoveQueueUp,
MoveQueueDown,
/// Download the selected federated track(s) into the local library.
DownloadSelected,
RemoveFromQueue,
ClearQueue,
OpenConnectedDevices,
OpenListenHistory,
GoToRelease,
AddToPlaylist,
NewPlaylist,
ToggleHelp,
ToggleViewMode,
OpenDevices,
CycleSourceMode,
OpenLibraryFilters,
OpenCommandLine,
OpenSearch,
Logout,
EditSelected,
DeleteSelected,
/// Podcasts: subscribe to an RSS feed URL.
AddPodcast,
/// Podcasts: search the episodes of the opened podcast.
SearchEpisodes,
/// Podcasts: check the selected or opened podcast for new episodes.
RefreshPodcast,
/// Podcasts: check every subscription for new episodes.
RefreshAllPodcasts,
/// Podcasts: cycle the episode order.
CycleEpisodeSort,
/// Podcasts: cycle the played-state filter.
CycleEpisodeFilter,
/// Podcasts: mark the selected episode played / unplayed.
ToggleEpisodePlayed,
/// Podcasts: unsubscribe (progress and history are kept).
UnsubscribePodcast,
/// Podcasts: play the selected (or playing) episode from the beginning.
RestartEpisode,
/// Podcasts: turn "share in the federation" on or off for the selected
/// or opened podcast (asks first when its feed URL looks private).
TogglePodcastShare,
}
/// Help-window sections, in display order.
@@ -50,16 +85,20 @@ pub enum Action {
pub enum Category {
Playback,
Queue,
Library,
Navigation,
Podcasts,
Search,
System,
}
impl Category {
pub const ALL: [Category; 5] = [
pub const ALL: [Category; 7] = [
Category::Playback,
Category::Queue,
Category::Library,
Category::Navigation,
Category::Podcasts,
Category::Search,
Category::System,
];
@@ -68,7 +107,9 @@ impl Category {
match self {
Category::Playback => "Playback",
Category::Queue => "Queue & playlists",
Category::Library => "Library",
Category::Navigation => "Navigation",
Category::Podcasts => "Podcasts",
Category::Search => "Search & commands",
Category::System => "System",
}
@@ -86,16 +127,23 @@ impl Action {
| Action::VolumeUp
| Action::VolumeDown
| Action::ToggleShuffle
| Action::CycleRepeat => Category::Playback,
| Action::CycleRepeat
| Action::ToggleVisualizer
| Action::OpenConnectedDevices
| Action::OpenListenHistory => Category::Playback,
Action::QueueAddNext
| Action::QueueAddLast
| Action::MoveQueueUp
| Action::MoveQueueDown
| Action::DownloadSelected
| Action::RemoveFromQueue
| Action::ClearQueue
| Action::AddToPlaylist
| Action::NewPlaylist
| Action::ToggleLike
| Action::ToggleTrackSelection
| Action::OpenTrackInfo => Category::Queue,
| Action::OpenTrackInfo
| Action::OpenCurrentTrackInfo => Category::Queue,
Action::MoveUp
| Action::MoveDown
| Action::MoveLeft
@@ -111,9 +159,22 @@ impl Action {
| Action::GoToTab(_)
| Action::GoToRelease
| Action::ToggleViewMode => Category::Navigation,
Action::EditSelected
| Action::DeleteSelected
| Action::CycleSourceMode
| Action::OpenLibraryFilters => Category::Library,
Action::AddPodcast
| Action::SearchEpisodes
| Action::RefreshPodcast
| Action::RefreshAllPodcasts
| Action::CycleEpisodeSort
| Action::CycleEpisodeFilter
| Action::ToggleEpisodePlayed
| Action::UnsubscribePodcast
| Action::RestartEpisode
| Action::TogglePodcastShare => Category::Podcasts,
Action::OpenSearch | Action::OpenCommandLine => Category::Search,
Action::OpenDevices => Category::System,
Action::ToggleHelp | Action::Logout | Action::Quit => Category::System,
Action::ToggleHelp | Action::Quit => Category::System,
}
}
@@ -121,7 +182,7 @@ impl Action {
pub fn command_hint(&self) -> Option<&'static str> {
match self {
Action::Quit => Some(":q"),
Action::Logout => Some(":logout"),
Action::EditSelected => Some(":import <path> adds files"),
Action::PlayPause => Some(":play"),
Action::NextTrack => Some(":next"),
Action::PrevTrack => Some(":prev"),
@@ -130,7 +191,8 @@ impl Action {
Action::ToggleShuffle => Some(":shuffle"),
Action::CycleRepeat => Some(":repeat [off|one|all]"),
Action::ClearQueue => Some(":clear"),
Action::OpenDevices => Some(":devices"),
Action::OpenConnectedDevices => None,
Action::OpenListenHistory => None,
Action::ToggleHelp => Some(":help"),
Action::OpenSearch => Some("/text"),
_ => None,
@@ -142,7 +204,10 @@ impl Action {
Action::Quit => "Quit".into(),
Action::NextTab => "Next tab".into(),
Action::PrevTab => "Previous tab".into(),
Action::GoToTab(i) => format!("Go to tab {}", i + 1),
Action::GoToTab(i) => match crate::app::state::Tab::from_index(*i) {
Some(tab) => format!("Go to {}", tab.title()),
None => format!("Go to tab {}", i + 1),
},
Action::MoveUp => "Move up".into(),
Action::MoveDown => "Move down".into(),
Action::MoveLeft => "Move left".into(),
@@ -162,22 +227,41 @@ impl Action {
Action::VolumeDown => "Volume down".into(),
Action::ToggleShuffle => "Toggle shuffle".into(),
Action::CycleRepeat => "Cycle repeat mode".into(),
Action::ToggleVisualizer => "Toggle fullscreen visualizer".into(),
Action::ToggleLike => "Like / unlike".into(),
Action::ToggleTrackSelection => "Track line selection".into(),
Action::OpenTrackInfo => "Track info".into(),
Action::OpenCurrentTrackInfo => "Current track info".into(),
Action::QueueAddNext => "Queue: add next".into(),
Action::QueueAddLast => "Queue: add to end".into(),
Action::MoveQueueUp => "Queue: move track/selection up".into(),
Action::MoveQueueDown => "Queue: move track/selection down".into(),
Action::DownloadSelected => "Federation: download to library".into(),
Action::RemoveFromQueue => "Queue: remove selected".into(),
Action::ClearQueue => "Queue: clear".into(),
Action::OpenConnectedDevices => "Connected devices…".into(),
Action::OpenListenHistory => "Listening history…".into(),
Action::GoToRelease => "Open the track's release".into(),
Action::AddToPlaylist => "Add track to a playlist…".into(),
Action::NewPlaylist => "Create a playlist".into(),
Action::ToggleHelp => "Show / hide keybindings".into(),
Action::ToggleViewMode => "Toggle tiles / table view".into(),
Action::OpenDevices => "Connected devices".into(),
Action::CycleSourceMode => "Cycle source mode: Local / My / Global".into(),
Action::OpenLibraryFilters => "Library filters…".into(),
Action::OpenCommandLine => "Command line (:help for commands)".into(),
Action::OpenSearch => "Search artists, releases, tracks".into(),
Action::Logout => "Sign out".into(),
Action::OpenSearch => "Search artists, releases, tracks, public podcasts".into(),
Action::EditSelected => "Edit the selected item".into(),
Action::DeleteSelected => "Delete the selected item".into(),
Action::AddPodcast => "Add podcast (RSS URL)".into(),
Action::SearchEpisodes => "Search episodes".into(),
Action::RefreshPodcast => "Check podcast for new episodes".into(),
Action::RefreshAllPodcasts => "Check all podcasts".into(),
Action::CycleEpisodeSort => "Episode order".into(),
Action::CycleEpisodeFilter => "Filter: all/unplayed/played".into(),
Action::ToggleEpisodePlayed => "Mark played / unplayed".into(),
Action::UnsubscribePodcast => "Unsubscribe (keeps progress)".into(),
Action::RestartEpisode => "Play episode from the start".into(),
Action::TogglePodcastShare => "Share podcast in the federation on/off".into(),
}
}
}
+204 -36
View File
@@ -2,9 +2,8 @@ use std::sync::Arc;
use std::sync::atomic::Ordering;
use std::time::Duration;
use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
use crossterm::event::{KeyCode, KeyEvent};
use crate::api::client::ApiError;
use crate::app::Runtime;
use crate::app::command::{self, Command, Parsed};
use crate::app::event::AppEvent;
@@ -18,32 +17,32 @@ pub fn handle_key(state: &mut AppState, runtime: &mut Runtime, key: KeyEvent) {
match key.code {
KeyCode::Esc => cancel(state),
KeyCode::Enter => commit(state, runtime),
KeyCode::Backspace => {
if state.cmdline.input.pop().is_none() {
// Backspace on an empty line closes it, like vim.
cancel(state);
return;
KeyCode::Up => {
if state.cmdline.history_previous() {
after_change(state, runtime);
}
after_change(state, runtime);
}
KeyCode::Char(c) if is_typing(key) => {
state.cmdline.input.push(c);
after_change(state, runtime);
KeyCode::Down => {
if state.cmdline.history_next() {
after_change(state, runtime);
}
}
// Backspace on an empty line closes it, like vim.
KeyCode::Backspace if state.cmdline.input.is_empty() => cancel(state),
_ => {
if state.cmdline.input.handle_key(key) {
after_change(state, runtime);
}
}
_ => {}
}
}
pub fn handle_paste(state: &mut AppState, runtime: &Runtime, pasted: &str) {
let cleaned: String = pasted.chars().filter(|c| !c.is_control()).collect();
state.cmdline.input.push_str(&cleaned);
state.cmdline.input.insert_str(&cleaned);
after_change(state, runtime);
}
fn is_typing(key: KeyEvent) -> bool {
key.modifiers.difference(KeyModifiers::SHIFT).is_empty()
}
/// Re-evaluate the input after every edit; live commands (search) take
/// effect immediately, while typing.
fn after_change(state: &mut AppState, runtime: &Runtime) {
@@ -59,7 +58,9 @@ fn apply_live(state: &mut AppState, runtime: &Runtime, command: Command) {
match command {
// One-shot commands have no live effect.
Command::Quit
| Command::Logout
| Command::Import(_)
| Command::Open(_)
| Command::ConnectInvite(_)
| Command::Volume(_)
| Command::Seek(_)
| Command::SeekTo(_)
@@ -70,7 +71,6 @@ fn apply_live(state: &mut AppState, runtime: &Runtime, command: Command) {
| Command::Prev
| Command::PlayPause
| Command::Help
| Command::Devices
| Command::Logs(_) => {}
Command::Search(query) => {
state.active_tab = Tab::Global;
@@ -96,17 +96,25 @@ fn set_view_cursor_zero(state: &mut AppState) {
/// Debounced, race-free search: every edit bumps the global sequence; the
/// spawned task only queries if it is still the latest after the debounce,
/// and the receiver drops responses that arrive out of date.
fn schedule_search(state: &mut AppState, runtime: &Runtime) {
pub(super) fn schedule_search(state: &mut AppState, runtime: &Runtime) {
state.search.similarity_source = None;
state.search.similarity_source_track = None;
state.search.similarity_tracks.clear();
state.search.similarity_stats = None;
state.search.similarity_error = None;
let seq = runtime.search_seq.fetch_add(1, Ordering::SeqCst) + 1;
let query = state.search.query.clone();
if query.is_empty() {
state.search.loading = false;
state.search.results = None;
state.search.fed_tracks.clear();
state.search.fed_artists.clear();
state.search.fed_podcasts.clear();
state.search.fed_loading = false;
state.search.fed_podcasts_loading = false;
return;
}
let Some(api) = runtime.api.clone() else {
return;
};
let library = Arc::clone(&runtime.library);
state.search.loading = true;
let tx = runtime.event_tx.clone();
let latest = Arc::clone(&runtime.search_seq);
@@ -115,25 +123,157 @@ fn schedule_search(state: &mut AppState, runtime: &Runtime) {
if latest.load(Ordering::SeqCst) != seq {
return;
}
let event = match api.search(&query, SEARCH_LIMIT).await {
Ok(results) => AppEvent::SearchLoaded {
seq,
result: Ok(results),
},
Err(ApiError::SessionExpired) => AppEvent::SessionExpired,
Err(err) => AppEvent::SearchLoaded {
seq,
result: Err(err.to_string()),
},
let result = tokio::task::spawn_blocking(move || library.search(&query, SEARCH_LIMIT))
.await
.map_err(|err| err.to_string())
.and_then(|result| result.map_err(|err| format!("{err:#}")));
let _ = tx.send(AppEvent::SearchLoaded { seq, result });
});
// The same query also runs against the federated network (when the
// node is up); its results render as a separate, marked section.
state.search.fed_tracks.clear();
state.search.fed_artists.clear();
state.search.fed_podcasts.clear();
state.search.fed_loading = false;
state.search.fed_podcasts_loading = false;
if runtime.federation.settings().enabled {
state.search.fed_loading = true;
let fed = Arc::clone(&runtime.federation);
let query = state.search.query.clone();
let tx = runtime.event_tx.clone();
let latest = Arc::clone(&runtime.search_seq);
tokio::spawn(async move {
tokio::time::sleep(SEARCH_DEBOUNCE).await;
if latest.load(Ordering::SeqCst) != seq {
return;
}
let result = fed.search(&query).await.map_err(|err| format!("{err:#}"));
let _ = tx.send(AppEvent::FedSearchLoaded { seq, result });
});
schedule_podcast_search(state, runtime, seq);
}
}
/// Public podcast cards for the live search `seq`, as their own task and
/// event: the overlay search (bounded, bootstrap included) never holds back
/// the music results.
fn schedule_podcast_search(state: &mut AppState, runtime: &Runtime, seq: u64) {
state.search.fed_podcasts_loading = true;
let fed = Arc::clone(&runtime.federation);
let query = state.search.query.clone();
let tx = runtime.event_tx.clone();
let latest = Arc::clone(&runtime.search_seq);
let podcast_store = runtime
.podcasts
.as_ref()
.map(|podcasts| Arc::clone(&podcasts.services.store));
tokio::spawn(async move {
tokio::time::sleep(SEARCH_DEBOUNCE).await;
if latest.load(Ordering::SeqCst) != seq {
return;
}
let mut hits = fed.search_podcasts(&query).await;
// Which public podcasts this device already knows (feed aliases
// included), for the "subscribed" mark.
if let Some(store) = podcast_store
&& !hits.is_empty()
{
hits = tokio::task::spawn_blocking(move || {
if let Err(err) = crate::podcasts::discovery::resolve_local_ids(&store, &mut hits) {
tracing::warn!("podcast search: feed aliases not resolved: {err:#}");
}
hits
})
.await
.unwrap_or_default();
}
let _ = tx.send(AppEvent::FedPodcastsLoaded { seq, hits });
});
}
pub(super) fn schedule_similarity_search(
state: &mut AppState,
runtime: &Runtime,
track: &crate::library::models::TrackItem,
) {
let seq = runtime.search_seq.fetch_add(1, Ordering::SeqCst) + 1;
let artist = track.artist_line();
state.search.query = if artist.is_empty() {
track.title.clone()
} else {
format!("{} — {artist}", track.title)
};
state.search.similarity_source = Some(track.id);
state.search.similarity_source_track = Some(track.clone());
state.search.similarity_tracks.clear();
state.search.similarity_stats = None;
state.search.similarity_error = None;
state.search.loading = true;
state.search.results = None;
state.search.fed_tracks.clear();
state.search.fed_artists.clear();
state.search.fed_podcasts.clear();
state.search.fed_loading = false;
state.search.fed_podcasts_loading = false;
state.active_tab = crate::app::state::Tab::Global;
if let Some(crate::app::state::GlobalView::Search { cursor }) = state.global.stack.last_mut() {
*cursor = 0;
} else {
state
.global
.stack
.push(crate::app::state::GlobalView::Search { cursor: 0 });
}
let similarity = Arc::clone(&runtime.similarity);
let tx = runtime.event_tx.clone();
let track_id = track.id;
tokio::task::spawn_blocking(move || {
let result = similarity
.search_track(track_id, 49)
.map(|(matches, query)| (matches, query));
let (result, query) = match result {
Ok((results, query)) => (Ok(results), Some(query)),
Err(err) => (Err(format!("{err:#}")), None),
};
let _ = tx.send(event);
let _ = tx.send(AppEvent::SimilaritySearchLoaded { seq, result, query });
});
}
/// Refresh only the local-library half of an already open search.
///
/// Library/device sync notifications can arrive while federated search
/// results are visible. Reusing `schedule_search` here would clear the
/// federation rows and bump the shared sequence, causing valid network
/// responses to be dropped or flicker away.
pub(super) fn refresh_local_search(state: &mut AppState, runtime: &Runtime) {
if state.search.similarity_source.is_some() {
return;
}
let query = state.search.query.clone();
if query.is_empty() {
return;
}
let seq = runtime.search_seq.load(Ordering::SeqCst);
let library = Arc::clone(&runtime.library);
state.search.loading = true;
let tx = runtime.event_tx.clone();
tokio::spawn(async move {
let result = tokio::task::spawn_blocking(move || library.search(&query, SEARCH_LIMIT))
.await
.map_err(|err| err.to_string())
.and_then(|result| result.map_err(|err| format!("{err:#}")));
let _ = tx.send(AppEvent::SearchLoaded { seq, result });
});
}
/// Enter: close the line. Live commands already took effect (their view
/// stays open); one-shot commands execute here.
fn commit(state: &mut AppState, runtime: &mut Runtime) {
let remembered = state.cmdline.input.as_str().to_string();
let parsed = command::parse(&state.cmdline.input);
state.cmdline.remember(&remembered);
close(state);
match parsed {
Parsed::Empty => {}
@@ -161,7 +301,9 @@ fn execute(state: &mut AppState, runtime: &mut Runtime, command: Command) {
match command {
Command::Search(_) => {}
Command::Quit => state.should_quit = true,
Command::Logout => super::perform_logout(state, runtime),
Command::Import(path) => super::spawn_import(state, runtime, &path),
Command::Open(link) => open_frid_link(state, runtime, link),
Command::ConnectInvite(invite) => super::device_connect(runtime, invite),
Command::Volume(value) => {
state.player.volume = value;
super::perform_effect(state, runtime, Effect::SetVolume(value));
@@ -194,7 +336,6 @@ fn execute(state: &mut AppState, runtime: &mut Runtime, command: Command) {
Command::Prev => run_action(state, runtime, Action::PrevTrack),
Command::PlayPause => run_action(state, runtime, Action::PlayPause),
Command::Help => state.help_visible = true,
Command::Devices => run_action(state, runtime, Action::OpenDevices),
Command::Logs(level) => {
if let Some(index) = level {
state.logs.level_index = index.min(LOG_LEVELS.len() - 1);
@@ -206,6 +347,32 @@ fn execute(state: &mut AppState, runtime: &mut Runtime, command: Command) {
}
}
fn open_frid_link(state: &mut AppState, runtime: &Runtime, link: String) {
let Some(link) = crate::share::parse_frid_link(&link) else {
state.status_message = Some("usage: :open frid://<content_id>".into());
return;
};
state.status_message = Some(match link.label.as_deref() {
Some(label) => format!("federation: opening \"{label}\"…"),
None => "federation: opening shared track…".into(),
});
let federation = Arc::clone(&runtime.federation);
let tx = runtime.event_tx.clone();
tokio::spawn(async move {
let event = match federation
.track_by_content_id(&link.content_id, link.label.as_deref())
.await
{
Ok(track) => AppEvent::EnqueueTracks {
tracks: vec![crate::federation::pending_track(&track)],
next: false,
},
Err(err) => AppEvent::StatusMessage(format!("open failed: {err:#}")),
};
let _ = tx.send(event);
});
}
/// Esc: close the line and undo any live effect it had.
fn cancel(state: &mut AppState) {
retract_live(state);
@@ -216,6 +383,7 @@ fn close(state: &mut AppState) {
state.cmdline.active = false;
state.cmdline.input.clear();
state.cmdline.live = false;
state.cmdline.begin_history_navigation();
}
/// Pop the live search view if this command-line session opened it.
+51 -8
View File
@@ -22,8 +22,13 @@ pub enum Command {
/// `:q` / `:quit` — exit immediately (explicit enough to skip the
/// double-press confirmation).
Quit,
/// `:logout` — sign out and return to the login screen.
Logout,
/// `:import <path>` — import an audio file or a directory into the
/// library.
Import(String),
/// `:open frid://...` — open a shared federation content link.
Open(String),
/// `:connect frid://i/...` — pair this client with a trusted device.
ConnectInvite(String),
/// `:volume 40` (also `:vol`) — set the volume precisely.
Volume(u8),
/// `:seek +30` / `:seek -10` — relative seek in seconds.
@@ -43,8 +48,6 @@ pub enum Command {
PlayPause,
/// `:help` — open the keybinding help.
Help,
/// `:devices` — open the connected-devices picker.
Devices,
/// `:logs [error|warn|info|debug|trace]` — jump to the Logs tab,
/// optionally setting the severity filter.
Logs(Option<usize>),
@@ -74,7 +77,31 @@ pub fn parse(input: &str) -> Parsed {
let arg = parts.next();
match name {
"q" | "quit" => Parsed::Command(Command::Quit),
"logout" => Parsed::Command(Command::Logout),
"import" | "add" => {
let path = input.trim_start().split_once(char::is_whitespace);
match path.map(|(_, rest)| rest.trim()) {
Some(path) if !path.is_empty() => {
Parsed::Command(Command::Import(path.to_string()))
}
_ => Parsed::Invalid("usage: :import <file or directory>".to_string()),
}
}
"open" => {
let value = input.trim_start().split_once(char::is_whitespace);
match value.map(|(_, rest)| rest.trim()) {
Some(value) if !value.is_empty() => Parsed::Command(Command::Open(value.into())),
_ => Parsed::Invalid("usage: :open frid://<content_id>".to_string()),
}
}
"connect" => {
let value = input.trim_start().split_once(char::is_whitespace);
match value.map(|(_, rest)| rest.trim()) {
Some(value) if !value.is_empty() => {
Parsed::Command(Command::ConnectInvite(value.into()))
}
_ => Parsed::Invalid("usage: :connect frid://i/<invite>".to_string()),
}
}
"volume" | "vol" => match arg.and_then(|a| a.parse::<u8>().ok()) {
Some(value) if value <= 100 => Parsed::Command(Command::Volume(value)),
_ => Parsed::Invalid("usage: :volume 0-100".to_string()),
@@ -96,7 +123,6 @@ pub fn parse(input: &str) -> Parsed {
"prev" => Parsed::Command(Command::Prev),
"pause" | "play" => Parsed::Command(Command::PlayPause),
"help" => Parsed::Command(Command::Help),
"devices" | "device" => Parsed::Command(Command::Devices),
"logs" => match arg {
None => Parsed::Command(Command::Logs(None)),
Some(level) => match ["error", "warn", "info", "debug", "trace"]
@@ -152,7 +178,25 @@ mod tests {
fn parses_word_commands() {
assert_eq!(parse("q"), Parsed::Command(Command::Quit));
assert_eq!(parse("quit"), Parsed::Command(Command::Quit));
assert_eq!(parse("logout"), Parsed::Command(Command::Logout));
assert_eq!(
parse("import ~/Music/My Album"),
Parsed::Command(Command::Import("~/Music/My Album".to_string()))
);
assert_eq!(
parse(
"open frid://b3:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef?t=A-B"
),
Parsed::Command(Command::Open(
"frid://b3:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef?t=A-B"
.to_string()
))
);
assert!(matches!(parse("import"), Parsed::Invalid(_)));
assert!(matches!(parse("open"), Parsed::Invalid(_)));
assert_eq!(
parse("connect frid://i/abcd"),
Parsed::Command(Command::ConnectInvite("frid://i/abcd".to_string()))
);
assert_eq!(parse("volume 40"), Parsed::Command(Command::Volume(40)));
assert_eq!(parse("vol 0"), Parsed::Command(Command::Volume(0)));
assert_eq!(parse("shuffle"), Parsed::Command(Command::Shuffle));
@@ -162,7 +206,6 @@ mod tests {
Parsed::Command(Command::Repeat(Some(RepeatArg::All)))
);
assert_eq!(parse("clear"), Parsed::Command(Command::ClearQueue));
assert_eq!(parse("devices"), Parsed::Command(Command::Devices));
assert_eq!(parse("logs debug"), Parsed::Command(Command::Logs(Some(3))));
}
+141
View File
@@ -0,0 +1,141 @@
//! Scheduling for local cards enriched by replaceable federation data.
use std::collections::HashMap;
use std::time::{Duration, Instant};
use super::state::{AppState, GlobalView, Loadable, Tab};
const REFRESH_INTERVAL: Duration = Duration::from_secs(30);
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub(super) enum Card {
Artist(i64),
Release(i64),
}
#[derive(Debug, Default)]
pub(super) struct RefreshState {
visible: Option<Card>,
/// None means a request is in flight; Some is its completion time.
requests: HashMap<Card, Option<Instant>>,
}
impl RefreshState {
pub(super) fn is_loading(&self, card: Card) -> bool {
matches!(self.requests.get(&card), Some(None))
}
fn begin(&mut self, visible: Option<Card>, now: Instant) -> bool {
let reopened = self.visible != visible;
self.visible = visible;
let Some(card) = visible else { return false };
match self.requests.get(&card) {
Some(None) => return false,
Some(Some(completed))
if !reopened && now.duration_since(*completed) < REFRESH_INTERVAL =>
{
return false;
}
_ => {}
}
self.requests.insert(card, None);
true
}
pub(super) fn complete(&mut self, card: Card, now: Instant) {
self.requests.insert(card, Some(now));
}
}
#[derive(Debug, PartialEq, Eq)]
pub(super) enum Request {
Artist {
id: i64,
name: String,
},
Release {
id: i64,
title: String,
artists: Vec<String>,
},
}
/// Called on navigation and maintenance ticks. A cached success or failure
/// must not suppress discovery for the rest of the session.
pub(super) fn prepare(state: &mut AppState, now: Instant) -> Option<Request> {
let visible = if state.federation.settings.enabled
&& state.global.filters.source_mode.includes_network()
&& state.active_tab == Tab::Global
{
match state.global.stack.last() {
Some(GlobalView::Artist { id, .. }) => Some(Card::Artist(*id)),
Some(GlobalView::Release { id, .. }) => Some(Card::Release(*id)),
_ => None,
}
} else {
None
};
let request = match visible {
Some(Card::Artist(id)) => match state.artist_views.get(&id) {
Some(Loadable::Ready(detail)) => Some(Request::Artist {
id,
name: detail.name.clone(),
}),
_ => None,
},
Some(Card::Release(id)) => match state.release_views.get(&id) {
Some(Loadable::Ready(detail)) => {
let mut artists = Vec::new();
for artist in &detail.artists {
if !artists.iter().any(|name: &String| {
music_dht::normalize_name(name) == music_dht::normalize_name(&artist.name)
}) {
artists.push(artist.name.clone());
}
}
(!artists.is_empty()).then(|| Request::Release {
id,
title: detail.title.clone(),
artists,
})
}
_ => None,
},
None => None,
};
if !state
.card_enrichment
.begin(visible.filter(|_| request.is_some()), now)
{
return None;
}
match &request {
Some(Request::Artist { id, .. }) => mark_loading(&mut state.artist_fed_views, *id),
Some(Request::Release { id, .. }) => mark_loading(&mut state.release_fed_views, *id),
None => {}
}
request
}
fn mark_loading<T>(views: &mut HashMap<i64, Loadable<T>>, id: i64) {
if !matches!(views.get(&id), Some(Loadable::Ready(_))) {
views.insert(id, Loadable::Loading);
}
}
/// Keep the last usable snapshot if a refresh fails while peers are offline.
pub(super) fn store_result<T>(
views: &mut HashMap<i64, Loadable<T>>,
id: i64,
result: Result<T, String>,
) {
match result {
Ok(value) => {
views.insert(id, Loadable::Ready(value));
}
Err(message) if !matches!(views.get(&id), Some(Loadable::Ready(_))) => {
views.insert(id, Loadable::Failed(message));
}
Err(_) => {}
}
}
+244 -26
View File
@@ -1,25 +1,28 @@
use std::sync::Arc;
use crate::api::auth::AuthSession;
use crate::api::models::{
ArtistDetail, ArtistsPage, DevicePollResponse, PlaylistCard, PlaylistDetail, ReleaseDetail,
SearchResults, TrackItem,
};
use crate::art::ArtImage;
use crate::library::models::{
ArtistDetail, ArtistsPage, PlaylistCard, PlaylistDetail, ReleaseDetail, SearchResults,
TrackItem,
};
/// Events delivered to the main loop by background tasks (API fetches, the
/// playback engine, device sync). Tasks never touch AppState directly.
/// Events delivered to the main loop by background tasks (library queries,
/// the playback engine, imports). Tasks never touch AppState directly.
#[derive(Debug)]
pub enum AppEvent {
UpdateChecked(Result<Option<crate::updater::Update>, String>),
UpdateProgress(String),
UpdateInstalled(Result<(), String>),
StatusMessage(String),
LoginSucceeded(Box<AuthSession>),
LoginFailed(String),
/// Loopback listener received the browser SSO callback.
SsoCallback(Result<String, String>),
/// Refresh token rejected — stored credentials were deleted.
SessionExpired,
/// A page of the Global artists list arrived (or failed).
StatusVisualizationReady(crate::visualizer::status::Ready),
/// A page of the artists list arrived (or failed).
ArtistsLoaded(Result<ArtistsPage, String>),
/// A full reload after a library change: replaces the loaded artist
/// list wholesale, so the grid never flashes empty.
ArtistsReloaded {
page: ArtistsPage,
limit: i64,
},
ArtistViewLoaded {
id: i64,
result: Result<ArtistDetail, String>,
@@ -28,12 +31,32 @@ pub enum AppEvent {
id: i64,
result: Result<ReleaseDetail, String>,
},
/// Federated tracks that complete an already-open local release view.
ReleaseFederationLoaded {
id: i64,
result: Result<Option<crate::federation::FedRelease>, String>,
},
/// Live search results; `seq` drops responses that are already stale.
SearchLoaded {
seq: u64,
result: Result<SearchResults, String>,
},
/// Artwork fetched and decoded for the shared art cache.
/// Local similar-track search completed. It uses the same sequence as
/// text search so stale pages cannot overwrite a newer request.
SimilaritySearchLoaded {
seq: u64,
result: Result<Vec<crate::similarity::SimilarTrack>, String>,
query: Option<crate::similarity::QueryVector>,
},
/// Federated candidates and diagnostics for a track-seeded search.
FedSimilaritySearchLoaded {
seq: u64,
result: Result<crate::federation::FedSimilaritySearchResults, String>,
},
SimilarityStatus(crate::similarity::SimilarityStatus),
/// `None` is emitted after clearing every stored embedding.
SimilarityProfileActivated(Option<String>),
/// Artwork loaded and decoded for the shared art cache.
ArtLoaded {
key: String,
art: Option<Arc<ArtImage>>,
@@ -41,7 +64,7 @@ pub enum AppEvent {
Player(crate::player::PlayerEvent),
/// A command from the OS media keys.
Media(crate::media::MediaCommand),
/// Gapless prefetch could not open the stream; the normal track-switch
/// Gapless prefetch could not open the file; the normal track-switch
/// path takes over when the current track ends.
PrefetchFailed {
pos: usize,
@@ -51,17 +74,30 @@ pub enum AppEvent {
id: i64,
result: Result<PlaylistDetail, String>,
},
/// Liked track ids for the ♥ markers.
LikesLoaded(Result<Vec<i64>, String>),
/// Liked local content ids for the ♥ markers.
LikesLoaded(Result<Vec<String>, String>),
/// Local-library content ids for availability markers.
LocalContentIdsLoaded(Result<Vec<String>, String>),
/// Counts and storage footprint of the local library/database.
LocalLibraryStatsLoaded(Result<crate::library::LocalLibraryStats, String>),
MusicDirectoryValidated(Result<std::path::PathBuf, String>),
MusicDirectoryChanged(Result<crate::library::MusicRelocationStats, String>),
ListenHistoryLoaded(Result<Vec<crate::library::ListenHistoryEntry>, String>),
/// One content id became available locally while the UI is open.
LocalContentAvailable {
content_id: String,
},
LikeToggled {
track_id: i64,
content_id: String,
liked: bool,
},
/// Liked federated item ids and content ids for the ♥ markers.
FedLikesLoaded(Result<Vec<String>, String>),
FedLikeToggled {
item_id: String,
content_id: Option<String>,
liked: bool,
},
/// Connected-devices poll result; carries device list, active id,
/// remote playback state and commands for this TUI.
DevicesPolled(Result<DevicePollResponse, String>),
/// Response from switching the active device.
DeviceActivated(Result<DevicePollResponse, String>),
/// A release fetched for queueing (a / shift-a on a release).
EnqueueTracks {
tracks: Vec<TrackItem>,
@@ -69,12 +105,194 @@ pub enum AppEvent {
},
PlaylistCreated {
result: Result<PlaylistCard, String>,
/// Add this track to the new playlist right away (Shift-P flow).
add_track: Option<TrackItem>,
/// Add this target to the new playlist right away (Shift-P flow).
add_target: Option<crate::app::state::PlaylistAddTarget>,
},
PlaylistTracksAdded {
playlist_id: i64,
playlist_title: String,
result: Result<(), String>,
},
/// The library was mutated (import, edit, delete): cached views must be
/// dropped and reloaded lazily.
LibraryChanged {
message: Option<String>,
},
/// Progress of a running import, shown in the status bar.
ImportProgress {
done: usize,
total: usize,
current: String,
},
/// Fresh copies of the queued tracks after a library change. Tracks
/// missing from the result were deleted and leave the queue.
QueueTracksRefreshed {
tracks: Vec<TrackItem>,
},
/// A status snapshot for the Federation tab.
/// Boxed to keep `AppEvent` small; the status is large and rare.
FederationStatus(Box<crate::federation::FedStatus>),
/// Federated live-search results (artists a card can be opened for,
/// plus matching tracks).
FedSearchLoaded {
seq: u64,
result: Result<crate::federation::FedSearchResults, String>,
},
/// Public podcast cards for the same live search (`seq`), delivered on
/// their own so the music results never wait for the overlay. Already
/// resolved against the podcast store.
FedPodcastsLoaded {
seq: u64,
hits: Vec<crate::podcasts::discovery::PodcastHit>,
},
/// A federated artist card finished assembling.
FedArtistLoaded {
name: String,
result: Result<crate::federation::FedArtistCard, String>,
},
/// Federated enrichment for an already-open local artist view.
ArtistFederationLoaded {
id: i64,
name: String,
result: Result<crate::federation::FedArtistCard, String>,
},
/// A network-library source refreshed its cached top-artist slice.
NetworkArtistCacheUpdated {
source_id: String,
count: usize,
},
/// A streamed image for the open card arrived (artist image when
/// `release` is None, a release cover otherwise).
FedCardArt {
name: String,
release: Option<String>,
path: String,
},
/// A pending federated track finished downloading (or failed); the
/// queue swaps the placeholder for the resolved track.
FedTrackResolved {
placeholder_id: i64,
resolve_key: String,
result: Result<Box<crate::federation::FedPlayable>, String>,
},
/// Rich metadata for a federated track-info preview arrived without
/// downloading the audio file.
FedTrackInfoLoaded {
placeholder_id: i64,
item_id: String,
/// Boxed: `TrackItem` is large since it can carry a podcast episode.
result: Result<Box<TrackItem>, String>,
},
/// This peer's connection ticket, requested from the Federation tab.
FedTicket(Result<String, String>),
/// Immediate library publish finished.
FedSyncFinished(String),
/// Fresh personal-device sync status snapshot for Settings.
DeviceSyncStatus(crate::devices::DeviceSyncStatus),
/// Invite link for pairing another device.
DeviceInvite(Result<String, String>),
/// Result of `:connect frid://i/...`.
DeviceConnectResult(Result<String, String>),
/// Manual trusted-device sync finished.
DeviceSyncFinished(String),
/// Incoming pairing request that passed the invite-secret check.
DevicePairingRequest(crate::devices::PendingPairing),
/// Trusted device playback state, delivered by personal-device sync.
DevicePlayback(crate::devices::PlaybackSnapshot),
/// Playback command addressed to this device.
PlaybackCommand {
command: crate::devices::PlaybackCommand,
authority: music_dht::playback::CommandStamp,
origin: String,
},
/// Current lifecycle/status of the federation Jam.
JamStatus(crate::jam::JamStatus),
/// Host playback snapshot received by a Jam participant.
JamPlayback(crate::devices::PlaybackSnapshot),
/// Participant command accepted by this Jam host.
JamCommand(crate::devices::PlaybackCommand),
/// Result of creating/regenerating a Jam capability.
JamInvite(Result<String, String>),
/// Result of joining a Jam capability.
JamJoined(Result<String, String>),
/// Received podcast operations or snapshot sections changed the podcast
/// store: `progress` lists changed progress registers, `changed` means
/// anything else (subscriptions, feeds, sessions).
PodcastsSynced {
progress: Vec<music_dht::podcast::ProgressRecord>,
changed: bool,
},
/// The podcast store opened (with the feed client), or why it did not.
PodcastStoreOpened(Result<crate::podcasts::refresh::Services, String>),
/// Subscribed podcasts reloaded from the podcast store.
PodcastsLoaded(Result<Vec<crate::app::state::PodcastRow>, String>),
PodcastSeasonsLoaded {
podcast_id: music_dht::podcast::PodcastId,
result: Result<Vec<furumi_library::podcasts::SeasonSummary>, String>,
},
/// One page of episodes; `seq` drops results of older requests.
PodcastEpisodesLoaded {
seq: u64,
offset: usize,
result: Result<Vec<furumi_library::podcasts::EpisodeListItem>, String>,
},
PodcastSubscribed(Result<crate::podcasts::refresh::SubscribeReport, String>),
/// One feed check finished.
PodcastRefreshed {
podcast_id: music_dht::podcast::PodcastId,
result: Result<crate::podcasts::refresh::RefreshReport, String>,
/// Asked by the user (status bar), not the background scheduler.
manual: bool,
},
PodcastUnsubscribed {
podcast_id: music_dht::podcast::PodcastId,
title: String,
result: Result<(), String>,
},
/// Result of the progress writer (saves, supersedes, mark played).
PodcastProgress(crate::podcasts::progress::ProgressEvent),
/// An episode stream is playing; `generation` is the player source
/// generation of the start that requested it.
PodcastEpisodeStarted {
generation: u64,
episode: Box<music_dht::podcast::PodcastEpisodeRef>,
start_ms: i64,
duration_ms: Option<i64>,
/// The decoder measured `duration_ms` (else the feed announced it).
duration_measured: bool,
restart: bool,
/// The server allows seeking in the stream.
seekable: bool,
/// How the stream ended, once it does.
probe: crate::podcasts::stream::StreamProbe,
},
/// Starting an episode failed (network, decoding, cannot resume).
PodcastEpisodeFailed {
generation: u64,
message: String,
},
/// Scheduler timer: ask the store which feeds are due.
PodcastRefreshTick,
/// Feeds due for a background refresh.
PodcastsDue(Result<Vec<(music_dht::podcast::PodcastId, music_dht::podcast::FeedUrl)>, String>),
/// What sharing a podcast would publish (`Effect::PodcastPrepareShare`).
PodcastSharePrepared {
podcast_id: music_dht::podcast::PodcastId,
title: String,
result: Result<crate::podcasts::publication::ShareCheck, String>,
},
/// The share decision was written (`Effect::PodcastSetShared`).
PodcastShareSet {
podcast_id: music_dht::podcast::PodcastId,
title: String,
shared: bool,
result: Result<(), String>,
},
/// The publication reconciler finished a pass.
PodcastPublication(crate::podcasts::publication::PublicationReport),
/// A public card's feed was read for a preview (`Effect::PodcastPreview`).
PodcastPreviewLoaded {
podcast_id: music_dht::podcast::PodcastId,
result: Result<Box<crate::podcasts::discovery::FeedPreview>, String>,
},
}
+147
View File
@@ -0,0 +1,147 @@
//! One-line text editing with a movable cursor, shared by every text input
//! (command line, edit forms, popup fields).
use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
/// A single-line value plus a cursor position (in characters). Dereferences
/// to `&str`, so read paths treat it like the plain string it wraps.
#[derive(Debug, Clone, Default)]
pub struct LineEdit {
value: String,
cursor: usize,
}
impl LineEdit {
/// Starts with `value` and the cursor at its end.
pub fn new(value: impl Into<String>) -> Self {
let value = value.into();
let cursor = value.chars().count();
Self { value, cursor }
}
pub fn as_str(&self) -> &str {
&self.value
}
/// Cursor position in characters (0..=len).
pub fn cursor(&self) -> usize {
self.cursor
}
fn byte_index(&self, chars: usize) -> usize {
self.value
.char_indices()
.nth(chars)
.map(|(index, _)| index)
.unwrap_or(self.value.len())
}
pub fn clear(&mut self) {
self.value.clear();
self.cursor = 0;
}
pub fn insert(&mut self, c: char) {
let at = self.byte_index(self.cursor);
self.value.insert(at, c);
self.cursor += 1;
}
pub fn insert_str(&mut self, s: &str) {
let at = self.byte_index(self.cursor);
self.value.insert_str(at, s);
self.cursor += s.chars().count();
}
/// Removes the character before the cursor; `false` when at the start.
pub fn backspace(&mut self) -> bool {
if self.cursor == 0 {
return false;
}
let at = self.byte_index(self.cursor - 1);
self.value.remove(at);
self.cursor -= 1;
true
}
/// Removes the character under the cursor.
pub fn delete(&mut self) {
if self.cursor < self.value.chars().count() {
let at = self.byte_index(self.cursor);
self.value.remove(at);
}
}
/// Applies one editing key (characters, backspace/delete, cursor
/// movement). Returns `false` for keys this editor does not handle
/// (Enter, Esc, Tab, ...), which the caller interprets itself.
pub fn handle_key(&mut self, key: KeyEvent) -> bool {
match key.code {
KeyCode::Char(c) if key.modifiers.difference(KeyModifiers::SHIFT).is_empty() => {
self.insert(c);
}
KeyCode::Backspace => {
self.backspace();
}
KeyCode::Delete => self.delete(),
KeyCode::Left => self.cursor = self.cursor.saturating_sub(1),
KeyCode::Right => self.cursor = (self.cursor + 1).min(self.value.chars().count()),
KeyCode::Home => self.cursor = 0,
KeyCode::End => self.cursor = self.value.chars().count(),
_ => return false,
}
true
}
}
impl std::ops::Deref for LineEdit {
type Target = str;
fn deref(&self) -> &str {
&self.value
}
}
impl std::fmt::Display for LineEdit {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(&self.value)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crossterm::event::KeyEvent;
fn key(code: KeyCode) -> KeyEvent {
KeyEvent::new(code, KeyModifiers::NONE)
}
#[test]
fn edits_at_cursor() {
let mut edit = LineEdit::new("hllo");
assert_eq!(edit.cursor(), 4);
edit.handle_key(key(KeyCode::Home));
edit.handle_key(key(KeyCode::Right));
edit.handle_key(key(KeyCode::Char('e')));
assert_eq!(edit.as_str(), "hello");
assert_eq!(edit.cursor(), 2);
edit.handle_key(key(KeyCode::End));
edit.handle_key(key(KeyCode::Backspace));
assert_eq!(edit.as_str(), "hell");
edit.handle_key(key(KeyCode::Home));
edit.handle_key(key(KeyCode::Delete));
assert_eq!(edit.as_str(), "ell");
}
#[test]
fn multibyte_safe() {
let mut edit = LineEdit::new("метл");
edit.handle_key(key(KeyCode::Left));
edit.insert('а');
assert_eq!(edit.as_str(), "метал");
edit.handle_key(key(KeyCode::End));
edit.insert('л');
assert_eq!(edit.as_str(), "металл");
}
}
-221
View File
@@ -1,221 +0,0 @@
use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
use crate::api::{auth, client};
use crate::app::Runtime;
use crate::app::event::AppEvent;
use crate::app::sso;
use crate::app::state::{AppState, LoginField, LoginForm, LoginMode};
pub fn handle_key(state: &mut AppState, runtime: &mut Runtime, key: KeyEvent) {
if key.modifiers.contains(KeyModifiers::CONTROL) && key.code == KeyCode::Char('c') {
state.should_quit = true;
return;
}
let form = &mut state.login;
if form.busy {
return;
}
match form.mode {
LoginMode::Form => handle_form_key(form, runtime, key),
LoginMode::SsoPending => handle_sso_key(form, runtime, key),
}
}
/// Bracketed paste goes into whichever text field is focused.
pub fn handle_paste(state: &mut AppState, pasted: &str) {
let form = &mut state.login;
if form.busy {
return;
}
let cleaned: String = pasted.chars().filter(|c| !c.is_control()).collect();
if let Some(field) = focused_text(form) {
field.push_str(&cleaned);
}
}
fn handle_form_key(form: &mut LoginForm, runtime: &mut Runtime, key: KeyEvent) {
match key.code {
KeyCode::Tab | KeyCode::Down => form.focus = form.focus.next(),
KeyCode::BackTab | KeyCode::Up => form.focus = form.focus.prev(),
KeyCode::Backspace => {
if let Some(field) = focused_text(form) {
field.pop();
}
}
KeyCode::Enter => match form.focus {
LoginField::ServerUrl | LoginField::Username => form.focus = form.focus.next(),
LoginField::Password | LoginField::SignInButton => {
submit_password(form, runtime);
}
LoginField::SsoButton => start_sso(form, runtime),
},
KeyCode::Char(c) if is_typing(key) => {
if let Some(field) = focused_text(form) {
field.push(c);
}
}
_ => {}
}
}
fn handle_sso_key(form: &mut LoginForm, runtime: &mut Runtime, key: KeyEvent) {
// Ctrl-shortcuts first: plain letters belong to the paste field.
if key.modifiers.contains(KeyModifiers::CONTROL) {
match key.code {
// Copy the full SSO URL — terminals can't copy a wrapped link
// in one piece, the clipboard can.
KeyCode::Char('l') => {
form.error = None;
match copy_to_clipboard(&form.sso_url) {
Ok(()) => form.error = Some("link copied to clipboard".to_string()),
Err(err) => {
tracing::warn!(%err, "clipboard copy failed");
form.error = Some(format!("copy failed: {err}"));
}
}
}
KeyCode::Char('o') => {
if let Err(err) = open::that_detached(&form.sso_url) {
tracing::warn!(%err, "failed to reopen browser");
form.error = Some("couldn't open a browser".to_string());
}
}
_ => {}
}
return;
}
match key.code {
KeyCode::Esc => {
if let Some(listener) = runtime.sso.take() {
listener.abort();
}
form.mode = LoginMode::Form;
form.sso_paste.clear();
form.error = None;
}
KeyCode::Backspace => {
form.sso_paste.pop();
}
KeyCode::Enter => submit_sso_code(form, runtime),
KeyCode::Char(c) if is_typing(key) => form.sso_paste.push(c),
_ => {}
}
}
fn copy_to_clipboard(text: &str) -> Result<(), arboard::Error> {
arboard::Clipboard::new()?.set_text(text.to_string())
}
fn is_typing(key: KeyEvent) -> bool {
key.modifiers.difference(KeyModifiers::SHIFT).is_empty()
}
fn focused_text(form: &mut LoginForm) -> Option<&mut String> {
if form.mode == LoginMode::SsoPending {
return Some(&mut form.sso_paste);
}
match form.focus {
LoginField::ServerUrl => Some(&mut form.server_url),
LoginField::Username => Some(&mut form.username),
LoginField::Password => Some(&mut form.password),
LoginField::SignInButton | LoginField::SsoButton => None,
}
}
fn submit_password(form: &mut LoginForm, runtime: &Runtime) {
form.error = None;
let base_url = match auth::normalize_base_url(&form.server_url) {
Ok(url) => url,
Err(err) => return form.error = Some(err.to_string()),
};
let username = form.username.trim().to_string();
if username.is_empty() {
return form.error = Some("enter a username".to_string());
}
if form.password.is_empty() {
return form.error = Some("enter a password".to_string());
}
form.server_url = base_url.clone();
form.busy = true;
let password = form.password.clone();
let http = runtime.http.clone();
let tx = runtime.event_tx.clone();
tokio::spawn(async move {
let result = client::login_password(&http, &base_url, &username, &password).await;
let _ = tx.send(login_event(result));
});
}
fn start_sso(form: &mut LoginForm, runtime: &mut Runtime) {
form.error = None;
let base_url = match auth::normalize_base_url(&form.server_url) {
Ok(url) => url,
Err(err) => return form.error = Some(err.to_string()),
};
form.server_url = base_url.clone();
form.sso_paste.clear();
// Preferred flow: loopback listener, the browser redirect finishes the
// login hands-free. Fallback: furumi:// deep link + manual code paste.
if let Some(listener) = runtime.sso.take() {
listener.abort();
}
match sso::start(runtime.event_tx.clone()) {
Ok(listener) => {
let redirect = format!("http://127.0.0.1:{}/callback", listener.port);
form.sso_url = client::sso_start_url(&base_url, &redirect);
form.sso_port = Some(listener.port);
runtime.sso = Some(listener);
}
Err(err) => {
tracing::warn!(%err, "loopback listener unavailable, falling back to manual paste");
form.sso_url = client::sso_start_url(&base_url, "furumi://auth/callback");
form.sso_port = None;
}
}
form.mode = LoginMode::SsoPending;
if let Err(err) = open::that_detached(&form.sso_url) {
tracing::warn!(%err, "failed to open browser for SSO");
form.error = Some("couldn't open a browser — use the URL below".to_string());
}
}
fn submit_sso_code(form: &mut LoginForm, runtime: &Runtime) {
form.error = None;
let code = match auth::extract_sso_code(&form.sso_paste) {
Ok(code) => code,
Err(err) => return form.error = Some(err.to_string()),
};
spawn_sso_exchange(form, runtime, code);
}
/// Used by both the manual paste path and the loopback callback event.
pub fn spawn_sso_exchange(form: &mut LoginForm, runtime: &Runtime, code: String) {
let base_url = form.server_url.clone();
form.busy = true;
let http = runtime.http.clone();
let tx = runtime.event_tx.clone();
tokio::spawn(async move {
let result = client::login_sso_exchange(&http, &base_url, &code).await;
let _ = tx.send(login_event(result));
});
}
fn login_event(result: Result<auth::AuthSession, client::ApiError>) -> AppEvent {
match result {
Ok(session) => {
tracing::info!(user = %session.user.name, server = %session.server_base_url, "signed in");
if let Err(err) = auth::save_session(&session) {
tracing::warn!(%err, "failed to persist credentials");
}
AppEvent::LoginSucceeded(Box::new(session))
}
Err(err) => {
tracing::warn!(%err, "login failed");
AppEvent::LoginFailed(err.to_string())
}
}
}
+4316 -960
View File
File diff suppressed because it is too large. Load diff
+138
View File
@@ -0,0 +1,138 @@
//! Podcast state fixtures shared by update and rendering tests.
use furumi_library::podcasts::{
EpisodeListItem, EpisodeQuery, FetchState, PodcastSummary, SeasonSummary,
};
use music_dht::podcast::{
EpisodeId, EpisodeMeta, EpisodeType, FeedUrl, PodcastId, PodcastMeta, ProgressRecord,
ProgressStatus,
};
use crate::app::state::{
AppState, EpisodeList, Loadable, OpenedPodcast, PodcastRow, PodcastStoreStatus, Tab,
};
pub fn podcast_id() -> PodcastId {
PodcastId::from_feed_url(&FeedUrl::parse("https://example.test/feed.xml").unwrap())
}
pub fn row(title: &str, unplayed: u64, episodes: u64, seasons: u64) -> PodcastRow {
PodcastRow {
summary: PodcastSummary {
podcast_id: podcast_id(),
meta: PodcastMeta {
feed_url: FeedUrl::parse("https://example.test/feed.xml").unwrap(),
title: title.into(),
author: Some("Host".into()),
description: Some("A show about tests.".into()),
link: None,
image_url: None,
},
subscribed: true,
shared: false,
episode_count: episodes,
unplayed_count: unplayed,
in_progress_count: 0,
latest_published_at_ms: None,
season_count: seasons,
},
fetch: FetchState::default(),
}
}
pub fn episode(n: u32, title: &str, status: Option<(ProgressStatus, i64)>) -> EpisodeListItem {
let podcast = podcast_id();
let episode_id = EpisodeId::from_guid(&podcast, &format!("ep-{n}")).unwrap();
EpisodeListItem {
episode: EpisodeMeta {
episode_id: episode_id.clone(),
podcast_id: podcast.clone(),
guid: Some(format!("ep-{n}")),
title: title.into(),
description: Some(format!("Notes for {title}.")),
season: Some(1),
episode_number: Some(n),
episode_type: EpisodeType::Full,
published_at_ms: Some(1_718_409_600_000),
duration_ms: Some(2_700_000),
audio_url: format!("https://example.test/{n}.mp3"),
mime: Some("audio/mpeg".into()),
byte_len: None,
image_url: None,
link: None,
},
progress: status.map(|(status, position_ms)| ProgressRecord {
episode_id,
podcast_id: podcast,
position_ms,
status,
generation: 1,
session_id: "s".into(),
hlc_ms: 1,
device_id: "dev".into(),
op_id: "dev:1".into(),
}),
completed_count: 0,
in_feed: true,
}
}
pub fn ready_state(rows: Vec<PodcastRow>) -> AppState {
let mut state = AppState {
active_tab: Tab::Podcasts,
..AppState::default()
};
state.podcasts.store = PodcastStoreStatus::Ready;
state.podcasts.list = Some(Loadable::Ready(rows));
state
}
pub fn with_episodes(mut state: AppState, items: Vec<EpisodeListItem>) -> AppState {
let season = furumi_library::podcasts::SeasonFilter::Any;
state.podcasts.opened = Some(OpenedPodcast {
podcast_id: podcast_id(),
season_cursor: None,
season: Some(season),
episode_cursor: 0,
});
state.podcasts.episodes = Some(EpisodeList {
seq: 1,
query: EpisodeQuery::new(podcast_id()),
items,
loading: false,
loading_more: false,
complete: true,
error: None,
focus: None,
});
state
}
pub fn seasons() -> Vec<SeasonSummary> {
vec![
SeasonSummary {
season: Some(1),
episode_count: 3,
unplayed_count: 1,
first_published_at_ms: Some(1_609_459_200_000),
last_published_at_ms: Some(1_640_995_200_000),
},
SeasonSummary {
season: None,
episode_count: 2,
unplayed_count: 0,
first_published_at_ms: None,
last_published_at_ms: None,
},
]
}
/// Queue item for episode `n` of the fixture podcast ("Show").
pub fn episode_track(n: u32) -> crate::library::models::TrackItem {
let meta = row("Show", 0, 0, 0).summary.meta;
crate::library::models::TrackItem::podcast_episode(
episode(n, &format!("Episode {n}"), None)
.episode
.to_ref(&meta),
)
}
File diff suppressed because it is too large. Load diff
+1332 -118
View File
File diff suppressed because it is too large. Load diff
-134
View File
@@ -1,134 +0,0 @@
use std::io;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::sync::mpsc::UnboundedSender;
use crate::app::event::AppEvent;
/// Loopback callback listener for browser SSO (RFC 8252 native-app flow).
/// The backend 303-redirects the browser to `http://127.0.0.1:{port}/callback`
/// with the exchange code; the listener delivers it as an AppEvent and exits.
pub struct SsoListener {
pub port: u16,
handle: tokio::task::JoinHandle<()>,
}
impl SsoListener {
pub fn abort(&self) {
self.handle.abort();
}
}
pub fn start(tx: UnboundedSender<AppEvent>) -> io::Result<SsoListener> {
let listener = std::net::TcpListener::bind(("127.0.0.1", 0))?;
listener.set_nonblocking(true)?;
let port = listener.local_addr()?.port();
let handle = tokio::spawn(async move {
let result = match serve_one(listener).await {
Ok(result) => result,
Err(err) => Err(format!("callback listener failed: {err}")),
};
let _ = tx.send(AppEvent::SsoCallback(result));
});
Ok(SsoListener { port, handle })
}
async fn serve_one(listener: std::net::TcpListener) -> io::Result<Result<String, String>> {
let listener = tokio::net::TcpListener::from_std(listener)?;
loop {
let (mut stream, _) = listener.accept().await?;
let request_line = read_request_line(&mut stream).await?;
let Some(result) = parse_request_line(&request_line) else {
// Stray request (favicon, prefetch) — keep waiting for the code.
let _ = stream.write_all(&response(404, "Not Found")).await;
continue;
};
let page = match &result {
Ok(_) => "Sign-in complete. You can close this window and return to the terminal.",
Err(_) => "Sign-in failed. Return to the terminal to see the error.",
};
let _ = stream.write_all(&response(200, page)).await;
let _ = stream.shutdown().await;
return Ok(result);
}
}
async fn read_request_line(stream: &mut tokio::net::TcpStream) -> io::Result<String> {
let mut buf = vec![0u8; 8192];
let mut len = 0;
while len < buf.len() {
let n = stream.read(&mut buf[len..]).await?;
if n == 0 {
break;
}
len += n;
if buf[..len].windows(2).any(|w| w == b"\r\n") {
break;
}
}
let text = String::from_utf8_lossy(&buf[..len]);
Ok(text.lines().next().unwrap_or_default().to_string())
}
/// `GET /callback?code=furu_mx_... HTTP/1.1` → Ok(code) / Err(error).
/// Values are plain tokens (no percent-encoded characters expected).
fn parse_request_line(line: &str) -> Option<Result<String, String>> {
let path = line.split_whitespace().nth(1)?;
let query = path.split_once('?').map(|(_, q)| q).unwrap_or("");
let mut code = None;
let mut error = None;
for pair in query.split('&') {
let (key, value) = pair.split_once('=').unwrap_or((pair, ""));
match key {
"code" if !value.is_empty() => code = Some(value.to_string()),
"error" if !value.is_empty() => error = Some(value.to_string()),
_ => {}
}
}
if let Some(error) = error {
return Some(Err(format!("SSO failed: {error}")));
}
code.map(Ok)
}
fn response(status: u16, body: &str) -> Vec<u8> {
let reason = if status == 200 { "OK" } else { "Not Found" };
let body = format!(
"<!doctype html><html><head><meta charset=\"utf-8\"><title>furumi</title></head>\
<body style=\"font-family:sans-serif;background:#101114;color:#f5f2ea;\
display:grid;place-items:center;min-height:100vh;margin:0\"><p>{body}</p></body></html>"
);
format!(
"HTTP/1.1 {status} {reason}\r\nContent-Type: text/html; charset=utf-8\r\n\
Content-Length: {}\r\nConnection: close\r\n\r\n{body}",
body.len()
)
.into_bytes()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parses_code_from_request_line() {
assert_eq!(
parse_request_line("GET /callback?code=furu_mx_abc HTTP/1.1"),
Some(Ok("furu_mx_abc".to_string()))
);
}
#[test]
fn parses_error_from_request_line() {
assert_eq!(
parse_request_line("GET /callback?error=provider_denied HTTP/1.1"),
Some(Err("SSO failed: provider_denied".to_string()))
);
}
#[test]
fn ignores_unrelated_requests() {
assert_eq!(parse_request_line("GET /favicon.ico HTTP/1.1"), None);
assert_eq!(parse_request_line("GET /callback HTTP/1.1"), None);
}
}
+2036 -147
View File
File diff suppressed because it is too large. Load diff
+2134 -788
View File
File diff suppressed because it is too large. Load diff
+135
View File
@@ -0,0 +1,135 @@
//! Public podcast cards opened from the search results.
//!
//! The card shows what its publishers claim. "Подписаться" subscribes with
//! the card's origin feed URL only (`Effect::PodcastSubscribeFromCard`); the
//! subscription is private and its metadata comes from the feed. When this
//! device is already subscribed (under the card's id or a feed alias), the
//! action reads «Уже подписан» and Enter opens the podcast instead.
use crossterm::event::KeyCode;
use music_dht::podcast::PodcastId;
use super::Effect;
use super::podcasts::{display_title, reveal_podcast, store_ready};
use crate::app::state::{AppState, Loadable, Popup};
use crate::podcasts::discovery::{FeedPreview, PodcastHit};
/// Lines a page key scrolls the card by.
const PAGE: u16 = 10;
/// Enter on a podcast hit of the search results.
pub fn open_card(state: &mut AppState, index: usize) {
let Some(hit) = state.search.fed_podcasts.get(index) else {
return;
};
state.popup = Some(Popup::PodcastCard {
hit: Box::new(hit.clone()),
preview: None,
scroll: 0,
max_scroll: std::cell::Cell::new(u16::MAX),
});
}
/// A key in [`Popup::PodcastCard`] (the popup was taken out of the state):
/// Enter/s subscribes (or opens the subscribed podcast), `e` reads the
/// episodes from the feed, arrows and page keys scroll, Esc/q closes.
pub fn card_key(state: &mut AppState, popup: Popup, key: KeyCode) -> Option<Effect> {
let Popup::PodcastCard {
hit,
mut preview,
mut scroll,
max_scroll,
} = popup
else {
state.popup = Some(popup);
return None;
};
let mut effect = None;
match key {
KeyCode::Esc | KeyCode::Char('q') => return None,
KeyCode::Enter | KeyCode::Char('s') => {
if let Some(id) = subscribed_id(state, &hit, preview.as_ref()) {
// «Уже подписан»: show the subscription instead.
return reveal_podcast(state, id, hit.title());
}
effect = subscribe(state, &hit);
}
KeyCode::Char('e') => {
if !matches!(preview, Some(Loadable::Loading | Loadable::Ready(_))) {
preview = Some(Loadable::Loading);
effect = Some(Effect::PodcastPreview {
podcast_id: hit.hit.podcast_id.clone(),
feed_url: hit.hit.feed_url.clone(),
});
}
}
KeyCode::Up | KeyCode::Char('k') => scroll = scroll.saturating_sub(1),
KeyCode::Down | KeyCode::Char('j') => scroll = scroll.saturating_add(1),
KeyCode::PageUp => scroll = scroll.saturating_sub(PAGE),
KeyCode::PageDown => scroll = scroll.saturating_add(PAGE),
KeyCode::Home | KeyCode::Char('g') => scroll = 0,
_ => {}
}
// Never past the end the last draw measured, so scrolling back moves
// the view at once.
scroll = scroll.min(max_scroll.get());
state.popup = Some(Popup::PodcastCard {
hit,
preview,
scroll,
max_scroll,
});
effect
}
/// The id under which this device is subscribed to the card's podcast: the
/// card's id, the id its origin URL resolves to here (a feed alias), or —
/// once the feed was read — the podcast followed under the newer address
/// the feed moved to.
pub fn subscribed_id(
state: &AppState,
hit: &PodcastHit,
preview: Option<&Loadable<FeedPreview>>,
) -> Option<PodcastId> {
let moved = match preview {
Some(Loadable::Ready(preview)) => preview.subscribed_as.as_ref(),
_ => None,
};
hit.ids()
.into_iter()
.chain(moved)
.find(|id| state.podcasts.podcast(id).is_some())
.cloned()
}
fn subscribe(state: &mut AppState, hit: &PodcastHit) -> Option<Effect> {
if !store_ready(state) {
return None;
}
if state.podcasts.subscribing {
state.status_message = Some("podcasts: a subscription is already being added".into());
return None;
}
state.podcasts.subscribing = true;
state.status_message = Some(format!(
"podcasts: reading the feed of {}…",
display_title(hit.title())
));
Some(Effect::PodcastSubscribeFromCard(Box::new(hit.hit.clone())))
}
/// The preview of an open card arrived (ignored when another card is open).
pub fn preview_loaded(
state: &mut AppState,
podcast_id: PodcastId,
result: Result<Box<FeedPreview>, String>,
) {
if let Some(Popup::PodcastCard { hit, preview, .. }) = &mut state.popup
&& hit.hit.podcast_id == podcast_id
{
*preview = Some(match result {
Ok(feed) => Loadable::Ready(*feed),
Err(err) => Loadable::Failed(err),
});
}
}
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
+116 -14
View File
@@ -1,15 +1,27 @@
# Default keybindings for furumi.
#
# To customize, copy entries into <config dir>/furumi/keymap.toml
# (~/.config/furumi/keymap.toml on Linux/macOS). A user binding replaces the
# default binding with the same key sequence and context.
# To customize, copy entries into keymap.toml in the platform config dir
# (~/.config/furumi/keymap.toml on Linux,
# ~/Library/Application Support/furumi/keymap.toml on macOS). A user binding
# replaces the default binding with the same key sequence and context.
#
# version: keymap format version; put `version = 2` at the top of your file,
# before the first [[keymaps]] entry (after one, TOML attaches it to that
# entry and the file is rejected). Version 2 numbers tabs in this order:
# GoToTab = 0 Library, 1 Playlists, 2 Queue, 3 Podcasts, 4 Settings, 5 Logs.
# A file without `version` is treated as the older layout and its GoToTab
# indices are adapted in memory (3 -> 4 Settings, 4 -> 5 Logs, and 5 -> 3
# Podcasts from the prototype podcast build); the file itself is never
# rewritten. With `version = 2` indices are used exactly as written.
#
# key_sequence: space-separated chords, e.g. "g g" or "ctrl-a x".
# Modifiers: ctrl-, alt-, shift-, cmd-. Uppercase letters: "shift-g".
# command: an Action name, optionally with parameters:
# command = { SeekForward = { seconds = 30 } }
# context: optional view filter — global (default), library, search,
# playlists, queue, devices.
# playlists, queue, podcasts, settings, logs.
version = 2
[[keymaps]]
key_sequence = "q"
@@ -47,6 +59,18 @@ command = { GoToTab = 2 }
key_sequence = "4"
command = { GoToTab = 3 }
[[keymaps]]
key_sequence = "5"
command = { GoToTab = 4 }
[[keymaps]]
key_sequence = "6"
command = { GoToTab = 5 }
[[keymaps]]
key_sequence = "y"
command = "DownloadSelected"
[[keymaps]]
key_sequence = "a"
command = "QueueAddNext"
@@ -56,10 +80,19 @@ key_sequence = "shift-a"
command = "QueueAddLast"
[[keymaps]]
key_sequence = "shift-c"
command = "ClearQueue"
key_sequence = "alt-k"
command = "MoveQueueUp"
context = "queue"
[[keymaps]]
key_sequence = "alt-j"
command = "MoveQueueDown"
context = "queue"
[[keymaps]]
key_sequence = "shift-c"
command = "OpenConnectedDevices"
[[keymaps]]
key_sequence = "d"
command = "RemoveFromQueue"
@@ -78,11 +111,6 @@ command = "GoToRelease"
key_sequence = "shift-p"
command = "AddToPlaylist"
[[keymaps]]
key_sequence = "n"
command = "NewPlaylist"
context = "playlists"
[[keymaps]]
key_sequence = "j"
command = "MoveDown"
@@ -191,6 +219,14 @@ command = "ToggleShuffle"
key_sequence = "r"
command = "CycleRepeat"
[[keymaps]]
key_sequence = "shift-l"
command = "ToggleVisualizer"
[[keymaps]]
key_sequence = "shift-h"
command = "OpenListenHistory"
[[keymaps]]
key_sequence = "x"
command = "ToggleLike"
@@ -204,17 +240,30 @@ key_sequence = "i"
command = "OpenTrackInfo"
[[keymaps]]
key_sequence = "shift-l"
command = "Logout"
key_sequence = "shift-i"
command = "OpenCurrentTrackInfo"
[[keymaps]]
key_sequence = "e"
command = "EditSelected"
[[keymaps]]
key_sequence = "shift-d"
command = "OpenDevices"
command = "DeleteSelected"
[[keymaps]]
key_sequence = "v"
command = "ToggleViewMode"
[[keymaps]]
key_sequence = "m"
command = "CycleSourceMode"
[[keymaps]]
key_sequence = "f"
command = "OpenLibraryFilters"
context = "library"
[[keymaps]]
key_sequence = ":"
command = "OpenCommandLine"
@@ -222,3 +271,56 @@ command = "OpenCommandLine"
[[keymaps]]
key_sequence = "/"
command = "OpenSearch"
# Podcasts tab. Enter opens a podcast, its seasons and episodes, and plays
# an episode (continuing where you stopped); Esc goes back. a / shift-a queue
# the episode; Shift-D also unsubscribes here.
[[keymaps]]
key_sequence = "o"
command = "AddPodcast"
context = "podcasts"
[[keymaps]]
key_sequence = "/"
command = "SearchEpisodes"
context = "podcasts"
[[keymaps]]
key_sequence = "shift-r"
command = "RefreshPodcast"
context = "podcasts"
[[keymaps]]
key_sequence = "ctrl-r"
command = "RefreshAllPodcasts"
context = "podcasts"
[[keymaps]]
key_sequence = "shift-s"
command = "CycleEpisodeSort"
context = "podcasts"
[[keymaps]]
key_sequence = "f"
command = "CycleEpisodeFilter"
context = "podcasts"
[[keymaps]]
key_sequence = "m"
command = "ToggleEpisodePlayed"
context = "podcasts"
[[keymaps]]
key_sequence = "shift-u"
command = "UnsubscribePodcast"
context = "podcasts"
[[keymaps]]
key_sequence = "b"
command = "RestartEpisode"
context = "podcasts"
[[keymaps]]
key_sequence = "shift-f"
command = "TogglePodcastShare"
context = "podcasts"
+460 -29
View File
@@ -9,6 +9,14 @@ use crate::app::action::Action;
const DEFAULT_KEYMAP: &str = include_str!("default_keymap.toml");
/// Current keymap file format, declared as a top-level `version = 2`.
///
/// Version 2 introduced the tab order Library, Playlists, Queue, Podcasts,
/// Settings, Logs. Files without a version (or with `version = 1`) were
/// written for the older order and have their `GoToTab` indices remapped in
/// memory; the user's file itself is never rewritten.
pub const KEYMAP_VERSION: u32 = 2;
/// Input context a binding applies to. `Global` bindings work everywhere;
/// view-specific bindings shadow global ones for the same key sequence.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize)]
@@ -20,7 +28,9 @@ pub enum KeyContext {
Search,
Playlists,
Queue,
Devices,
Podcasts,
#[serde(rename = "settings", alias = "federation")]
Federation,
Logs,
}
@@ -32,7 +42,8 @@ impl KeyContext {
KeyContext::Search => "search",
KeyContext::Playlists => "playlists",
KeyContext::Queue => "queue",
KeyContext::Devices => "devices",
KeyContext::Podcasts => "podcasts",
KeyContext::Federation => "settings",
KeyContext::Logs => "logs",
}
}
@@ -51,10 +62,18 @@ struct RawBinding {
command: Action,
#[serde(default)]
context: KeyContext,
/// Never valid here: a `version = N` line written after a `[[keymaps]]`
/// header lands inside that entry. Caught so the file is not silently
/// treated as legacy (and its tab indices remapped) despite the version.
#[serde(default)]
version: Option<toml::Value>,
}
#[derive(Debug, Default, Deserialize)]
struct KeymapFile {
/// Format version; `None` means a legacy (pre-version-2) file.
#[serde(default)]
version: Option<u32>,
#[serde(default)]
keymaps: Vec<RawBinding>,
}
@@ -81,19 +100,25 @@ impl Keymap {
let mut bindings =
parse_bindings(DEFAULT_KEYMAP).expect("embedded default keymap must parse");
let mut warning = None;
if let Some(path) = user_keymap_path() {
if path.exists() {
match fs::read_to_string(&path)
.map_err(anyhow::Error::from)
.and_then(|text| parse_bindings(&text))
{
Ok(user) => merge(&mut bindings, user),
Err(err) => {
warning = Some(format!(
"{} ignored: {err:#}; using default keybindings",
path.display()
));
if let Some(path) = user_keymap_path()
&& path.exists()
{
match fs::read_to_string(&path)
.map_err(anyhow::Error::from)
.and_then(|text| parse_user_keymap(&text))
{
Ok(user) => {
if let Some(notice) = user.notice {
tracing::info!(path = %path.display(), "{notice}");
warning = Some(format!("{}: {notice}", path.display()));
}
merge(&mut bindings, user.bindings);
}
Err(err) => {
warning = Some(format!(
"{} ignored: {err:#}; using default keybindings",
path.display()
));
}
}
}
@@ -105,6 +130,16 @@ impl Keymap {
(keymap, warning)
}
/// The embedded defaults only, without reading the user's file.
#[cfg(test)]
pub(crate) fn defaults() -> Self {
Self {
bindings: parse_bindings(DEFAULT_KEYMAP).expect("embedded default keymap must parse"),
pending: Vec::new(),
format: KeyCombinationFormat::default(),
}
}
/// Feed one key combination; returns an action, a pending-chord state, or
/// nothing. Esc clears a pending chord instead of resolving.
pub fn resolve(&mut self, key: KeyCombination, context: KeyContext) -> KeyResolution {
@@ -219,10 +254,11 @@ enum Lookup {
/// Letters (of any alphabet) keep SHIFT (that is how "shift-g" works);
/// symbols drop it so a "?" binding matches everywhere.
fn normalize(key: KeyCombination) -> KeyCombination {
if let crokey::OneToThree::One(KeyCode::Char(c)) = key.codes {
if !c.is_alphabetic() && key.modifiers.contains(KeyModifiers::SHIFT) {
return KeyCombination::new(KeyCode::Char(c), key.modifiers - KeyModifiers::SHIFT);
}
if let crokey::OneToThree::One(KeyCode::Char(c)) = key.codes
&& !c.is_alphabetic()
&& key.modifiers.contains(KeyModifiers::SHIFT)
{
return KeyCombination::new(KeyCode::Char(c), key.modifiers - KeyModifiers::SHIFT);
}
key
}
@@ -273,10 +309,76 @@ pub fn user_keymap_path() -> Option<PathBuf> {
}
fn parse_bindings(text: &str) -> Result<Vec<Binding>> {
parse_file(text).map(|(_, bindings)| bindings)
}
/// A user keymap after version handling, plus a one-time, non-blocking
/// notice for the status bar and log when its meaning was adapted.
struct UserKeymap {
bindings: Vec<Binding>,
notice: Option<String>,
}
fn parse_user_keymap(text: &str) -> Result<UserKeymap> {
let (version, mut bindings) = parse_file(text)?;
let notice = match version {
None | Some(1) => {
let remapped = remap_legacy_tab_indices(&mut bindings);
(remapped > 0).then(|| {
format!(
"{remapped} tab shortcut(s) adapted to the new tab order \
(4 Podcasts, 5 Settings, 6 Logs); \
add `version = {KEYMAP_VERSION}` to use indices as written"
)
})
}
Some(KEYMAP_VERSION) => None,
Some(0) => bail!("unsupported keymap version 0"),
Some(newer) => Some(format!(
"keymap version {newer} is newer than this build supports \
({KEYMAP_VERSION}); bindings are used as written"
)),
};
Ok(UserKeymap { bindings, notice })
}
/// Pre-version-2 `GoToTab` index → current index. Index 5 only existed in the
/// prototype podcast build, where it opened Podcasts.
fn legacy_tab_index(index: usize) -> usize {
match index {
3 => 4, // Settings
4 => 5, // Logs
5 => 3, // Podcasts (prototype)
other => other,
}
}
/// Rewrites legacy `GoToTab` indices in memory; returns how many changed.
fn remap_legacy_tab_indices(bindings: &mut [Binding]) -> usize {
let mut remapped = 0;
for binding in bindings {
if let Action::GoToTab(index) = &mut binding.action {
let current = legacy_tab_index(*index);
if current != *index {
*index = current;
remapped += 1;
}
}
}
remapped
}
fn parse_file(text: &str) -> Result<(Option<u32>, Vec<Binding>)> {
let file: KeymapFile = toml::from_str(text).context("invalid TOML")?;
file.keymaps
let bindings = file
.keymaps
.into_iter()
.map(|raw| {
if raw.version.is_some() {
bail!(
"`version` must be a top-level key placed before the first [[keymaps]] entry"
);
}
let keys = parse_sequence(&raw.key_sequence)
.with_context(|| format!("bad key_sequence {:?}", raw.key_sequence))?;
Ok(Binding {
@@ -285,7 +387,8 @@ fn parse_bindings(text: &str) -> Result<Vec<Binding>> {
context: raw.context,
})
})
.collect()
.collect::<Result<_>>()?;
Ok((file.version, bindings))
}
fn parse_sequence(s: &str) -> Result<Vec<KeyCombination>> {
@@ -303,15 +406,15 @@ fn parse_chord(chord: &str) -> Result<KeyCombination> {
// crokey only parses single-byte characters; non-ASCII keys (Cyrillic
// bindings) are built directly.
let mut chars = chord.chars();
if let (Some(c), None) = (chars.next(), chars.next()) {
if !c.is_ascii() {
let modifiers = if c.is_uppercase() {
KeyModifiers::SHIFT
} else {
KeyModifiers::NONE
};
return Ok(KeyCombination::new(KeyCode::Char(c), modifiers));
}
if let (Some(c), None) = (chars.next(), chars.next())
&& !c.is_ascii()
{
let modifiers = if c.is_uppercase() {
KeyModifiers::SHIFT
} else {
KeyModifiers::NONE
};
return Ok(KeyCombination::new(KeyCode::Char(c), modifiers));
}
KeyCombination::from_str(chord)
.map_err(|e| anyhow::anyhow!("{e}"))
@@ -415,6 +518,94 @@ mod tests {
);
}
#[test]
fn default_playlist_context_keeps_next_track_on_n() {
let mut km = keymap_from(DEFAULT_KEYMAP);
assert_eq!(
km.resolve(key!(n), KeyContext::Playlists),
KeyResolution::Action(Action::NextTrack)
);
}
#[test]
fn default_source_mode_key_resolves_on_content_tabs() {
let mut km = keymap_from(DEFAULT_KEYMAP);
for context in [
KeyContext::Library,
KeyContext::Playlists,
KeyContext::Queue,
] {
assert_eq!(
km.resolve(key!(m), context),
KeyResolution::Action(Action::CycleSourceMode)
);
}
}
#[test]
fn default_shift_n_is_unbound() {
let mut km = keymap_from(DEFAULT_KEYMAP);
let shift_n = KeyCombination::new(KeyCode::Char('N'), KeyModifiers::SHIFT);
assert_eq!(
km.resolve(shift_n, KeyContext::Library),
KeyResolution::Unmatched
);
assert_eq!(
km.resolve(shift_n, KeyContext::Playlists),
KeyResolution::Unmatched
);
}
#[test]
fn default_add_to_playlist_key_is_global() {
let mut km = keymap_from(DEFAULT_KEYMAP);
let shift_p = KeyCombination::new(KeyCode::Char('P'), KeyModifiers::SHIFT);
assert_eq!(
km.resolve(shift_p, KeyContext::Library),
KeyResolution::Action(Action::AddToPlaylist)
);
}
#[test]
fn default_current_track_info_key_resolves() {
let mut km = keymap_from(DEFAULT_KEYMAP);
let shift_i = KeyCombination::new(KeyCode::Char('I'), KeyModifiers::SHIFT);
assert_eq!(
km.resolve(shift_i, KeyContext::Library),
KeyResolution::Action(Action::OpenCurrentTrackInfo)
);
}
#[test]
fn default_visualizer_key_resolves() {
let mut km = keymap_from(DEFAULT_KEYMAP);
let shift_l = KeyCombination::new(KeyCode::Char('L'), KeyModifiers::SHIFT);
assert_eq!(
km.resolve(shift_l, KeyContext::Library),
KeyResolution::Action(Action::ToggleVisualizer)
);
}
#[test]
fn settings_context_keeps_federation_alias() {
let settings = parse_bindings(
r#"
[[keymaps]]
key_sequence = "z"
command = "ToggleHelp"
context = "settings"
[[keymaps]]
key_sequence = "x"
command = "ToggleHelp"
context = "federation"
"#,
)
.unwrap();
assert_eq!(settings[0].context, KeyContext::Federation);
assert_eq!(settings[1].context, KeyContext::Federation);
}
#[test]
fn user_binding_overrides_default() {
let mut bindings = parse_bindings(DEFAULT_KEYMAP).unwrap();
@@ -506,4 +697,244 @@ mod tests {
KeyResolution::Action(Action::SeekForward { seconds: 10 })
);
}
#[test]
fn default_keymap_declares_current_version() {
let (version, _) = parse_file(DEFAULT_KEYMAP).unwrap();
assert_eq!(version, Some(KEYMAP_VERSION));
assert!(parse_user_keymap(DEFAULT_KEYMAP).unwrap().notice.is_none());
}
#[test]
fn default_digit_keys_follow_tab_order() {
let mut km = keymap_from(DEFAULT_KEYMAP);
for (index, key) in ['1', '2', '3', '4', '5', '6'].into_iter().enumerate() {
let combo = KeyCombination::new(KeyCode::Char(key), KeyModifiers::NONE);
assert_eq!(
km.resolve(combo, KeyContext::Library),
KeyResolution::Action(Action::GoToTab(index))
);
}
}
fn go_to_tab_indices(bindings: &[Binding]) -> Vec<usize> {
bindings
.iter()
.filter_map(|b| match b.action {
Action::GoToTab(index) => Some(index),
_ => None,
})
.collect()
}
const LEGACY_TABS: &str = r#"
[[keymaps]]
key_sequence = "1"
command = { GoToTab = 0 }
[[keymaps]]
key_sequence = "f2"
command = { GoToTab = 2 }
[[keymaps]]
key_sequence = "f4"
command = { GoToTab = 3 }
[[keymaps]]
key_sequence = "f5"
command = { GoToTab = 4 }
[[keymaps]]
key_sequence = "f6"
command = { GoToTab = 5 }
context = "logs"
[[keymaps]]
key_sequence = "x"
command = "ToggleHelp"
"#;
#[test]
fn legacy_keymap_tab_indices_are_remapped_in_memory() {
let user = parse_user_keymap(LEGACY_TABS).unwrap();
// Settings 3 -> 4, Logs 4 -> 5, prototype Podcasts 5 -> 3.
assert_eq!(go_to_tab_indices(&user.bindings), [0, 2, 4, 5, 3]);
assert_eq!(user.bindings[4].context, KeyContext::Logs);
assert_eq!(user.bindings[5].action, Action::ToggleHelp);
let notice = user.notice.expect("remap must be reported");
assert!(notice.starts_with("3 tab shortcut(s)"), "{notice}");
assert!(notice.contains("version = 2"), "{notice}");
}
#[test]
fn explicit_version_one_is_treated_as_legacy() {
let user = parse_user_keymap(&format!("version = 1\n{LEGACY_TABS}")).unwrap();
assert_eq!(go_to_tab_indices(&user.bindings), [0, 2, 4, 5, 3]);
assert!(user.notice.is_some());
}
#[test]
fn legacy_keymap_without_changed_tab_indices_has_no_notice() {
let user = parse_user_keymap(
r#"
[[keymaps]]
key_sequence = "1"
command = { GoToTab = 0 }
[[keymaps]]
key_sequence = "q"
command = "Back"
"#,
)
.unwrap();
assert_eq!(go_to_tab_indices(&user.bindings), [0]);
assert!(user.notice.is_none());
}
#[test]
fn versioned_keymap_is_taken_literally() {
let user = parse_user_keymap(&format!("version = 2\n{LEGACY_TABS}")).unwrap();
assert_eq!(go_to_tab_indices(&user.bindings), [0, 2, 3, 4, 5]);
assert!(user.notice.is_none());
}
#[test]
fn newer_keymap_version_is_used_as_written_with_a_notice() {
let user = parse_user_keymap(&format!("version = 3\n{LEGACY_TABS}")).unwrap();
assert_eq!(go_to_tab_indices(&user.bindings), [0, 2, 3, 4, 5]);
assert!(user.notice.unwrap().contains("newer"));
}
#[test]
fn version_inside_a_keymaps_entry_is_rejected() {
// Appended at the end, TOML puts `version` into the last entry; the
// file must not silently fall back to the legacy remap.
let err = parse_user_keymap(
"[[keymaps]]\nkey_sequence = \"4\"\ncommand = { GoToTab = 3 }\nversion = 2\n",
)
.err()
.expect("misplaced version must be rejected");
assert!(
format!("{err:#}").contains("before the first [[keymaps]]"),
"{err:#}"
);
}
#[test]
fn unknown_keys_in_keymaps_entries_are_still_ignored() {
let user = parse_user_keymap(
"version = 2\n[[keymaps]]\nkey_sequence = \"4\"\ncommand = { GoToTab = 3 }\nnote = \"mine\"\n",
)
.unwrap();
assert_eq!(go_to_tab_indices(&user.bindings), [3]);
}
#[test]
fn keymap_version_zero_is_rejected() {
assert!(parse_user_keymap("version = 0").is_err());
}
#[test]
fn legacy_user_digit_override_keeps_its_old_target() {
let mut bindings = parse_bindings(DEFAULT_KEYMAP).unwrap();
// An old file that swapped "4" and "5" (Settings / Logs).
let user = parse_user_keymap(
r#"
[[keymaps]]
key_sequence = "4"
command = { GoToTab = 4 }
[[keymaps]]
key_sequence = "5"
command = { GoToTab = 3 }
"#,
)
.unwrap();
merge(&mut bindings, user.bindings);
let mut km = Keymap {
bindings,
pending: Vec::new(),
format: KeyCombinationFormat::default(),
};
let four = KeyCombination::new(KeyCode::Char('4'), KeyModifiers::NONE);
let five = KeyCombination::new(KeyCode::Char('5'), KeyModifiers::NONE);
let six = KeyCombination::new(KeyCode::Char('6'), KeyModifiers::NONE);
// Still Logs and Settings, now at their new indices.
assert_eq!(
km.resolve(four, KeyContext::Library),
KeyResolution::Action(Action::GoToTab(5))
);
assert_eq!(
km.resolve(five, KeyContext::Library),
KeyResolution::Action(Action::GoToTab(4))
);
// The new default "6" is untouched by the user's file.
assert_eq!(
km.resolve(six, KeyContext::Library),
KeyResolution::Action(Action::GoToTab(5))
);
}
#[test]
fn podcasts_context_parses() {
let bindings = parse_bindings(
r#"
[[keymaps]]
key_sequence = "z"
command = "ToggleHelp"
context = "podcasts"
"#,
)
.unwrap();
assert_eq!(bindings[0].context, KeyContext::Podcasts);
assert_eq!(KeyContext::Podcasts.label(), "podcasts");
}
#[test]
fn default_podcast_keys_resolve_only_in_the_podcasts_context() {
let mut km = keymap_from(DEFAULT_KEYMAP);
let shift = |c| KeyCombination::new(KeyCode::Char(c), KeyModifiers::SHIFT);
let cases = [
(key!(o), Action::AddPodcast),
(key!('/'), Action::SearchEpisodes),
(shift('R'), Action::RefreshPodcast),
(key!(ctrl - r), Action::RefreshAllPodcasts),
(shift('S'), Action::CycleEpisodeSort),
(key!(f), Action::CycleEpisodeFilter),
(key!(m), Action::ToggleEpisodePlayed),
(shift('U'), Action::UnsubscribePodcast),
(key!(b), Action::RestartEpisode),
(shift('F'), Action::TogglePodcastShare),
];
for (key, action) in cases {
assert_eq!(
km.resolve(key, KeyContext::Podcasts),
KeyResolution::Action(action.clone()),
"{action:?}"
);
assert_ne!(
km.resolve(key, KeyContext::Library),
KeyResolution::Action(action.clone()),
"{action:?} leaks into the library"
);
}
// Playback keys keep working on the Podcasts tab.
assert_eq!(
km.resolve(key!(space), KeyContext::Podcasts),
KeyResolution::Action(Action::PlayPause)
);
assert_eq!(
km.resolve(key!(n), KeyContext::Podcasts),
KeyResolution::Action(Action::NextTrack)
);
}
#[test]
fn default_listening_history_key_resolves() {
let mut km = keymap_from(DEFAULT_KEYMAP);
assert_eq!(
km.resolve(key!(shift - h), KeyContext::Library),
KeyResolution::Action(Action::OpenListenHistory)
);
}
}
+1 -47
View File
@@ -1,55 +1,9 @@
pub mod keymap;
pub mod logging;
pub mod settings;
use directories::ProjectDirs;
use std::fs;
use std::path::PathBuf;
use std::time::{SystemTime, UNIX_EPOCH};
pub fn project_dirs() -> Option<ProjectDirs> {
ProjectDirs::from("", "", "furumi")
}
pub fn device_id_path() -> Option<PathBuf> {
project_dirs().map(|dirs| dirs.config_dir().join("device_id"))
}
pub fn load_or_create_device_id() -> String {
if let Some(path) = device_id_path() {
if let Ok(raw) = fs::read_to_string(&path) {
let id = raw.trim();
if valid_device_id(id) {
return id.to_string();
}
}
let id = generate_device_id();
if let Some(parent) = path.parent() {
if let Err(err) = fs::create_dir_all(parent) {
tracing::warn!(path = %parent.display(), %err, "failed to create config directory");
return id;
}
}
if let Err(err) = fs::write(&path, &id) {
tracing::warn!(path = %path.display(), %err, "failed to persist device id");
}
return id;
}
generate_device_id()
}
fn valid_device_id(id: &str) -> bool {
!id.is_empty()
&& id.len() <= 128
&& id
.chars()
.all(|ch| ch.is_ascii_alphanumeric() || ch == '-' || ch == '_')
}
fn generate_device_id() -> String {
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_nanos())
.unwrap_or(0);
format!("tui-{nanos:x}-{:x}", std::process::id())
}
+209
View File
@@ -0,0 +1,209 @@
use anyhow::{Context as _, Result};
use serde::{Deserialize, Serialize};
use std::path::PathBuf;
pub use furumi_library::{LibraryFilters, LibrarySourceMode};
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SimilaritySettings {
/// Local embedding/search master switch. Network participation follows
/// federation and additionally requires the explicit privacy consent.
#[serde(default)]
pub enabled: bool,
#[serde(default = "default_similarity_model")]
pub model: String,
#[serde(default = "default_similarity_profile")]
pub profile: String,
#[serde(default = "default_similarity_workers")]
pub workers: usize,
/// Requester-side cosine score floor. This is search policy, not part of
/// the embedding profile, so changing it never invalidates vectors.
#[serde(default = "default_similarity_minimum_score")]
pub minimum_score: f32,
/// Requester-side diversity cap applied independently to local and
/// federated candidates.
#[serde(default = "default_similarity_max_tracks_per_artist")]
pub max_tracks_per_artist: usize,
#[serde(default)]
pub federation_consent: bool,
/// Exact fingerprint of the last fully usable profile. Keeping this
/// separate from the selected target lets an old index serve searches
/// while a newly selected model/profile is being calculated.
#[serde(default)]
pub active_profile: Option<String>,
}
impl Default for SimilaritySettings {
fn default() -> Self {
Self {
enabled: false,
model: default_similarity_model(),
profile: default_similarity_profile(),
workers: default_similarity_workers(),
minimum_score: default_similarity_minimum_score(),
max_tracks_per_artist: default_similarity_max_tracks_per_artist(),
federation_consent: false,
active_profile: None,
}
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct AppSettings {
#[serde(default)]
pub playback: music_dht::playback::Config,
#[serde(default = "default_volume")]
pub volume: u8,
#[serde(default)]
pub library: LibraryFilters,
/// Root used for music materialized from federation peers.
#[serde(default = "default_music_dir")]
pub music_dir: PathBuf,
#[serde(default)]
pub similarity: SimilaritySettings,
}
impl Default for AppSettings {
fn default() -> Self {
Self {
playback: music_dht::playback::Config::default(),
volume: default_volume(),
library: LibraryFilters::default(),
music_dir: default_music_dir(),
similarity: SimilaritySettings::default(),
}
}
}
impl AppSettings {
pub fn normalized(mut self) -> Self {
self.volume = self.volume.min(100);
if self.music_dir.as_os_str().is_empty() {
self.music_dir = default_music_dir();
}
if self.similarity.model.trim().is_empty() {
self.similarity.model = default_similarity_model();
}
if self.similarity.profile.trim().is_empty() {
self.similarity.profile = default_similarity_profile();
}
self.similarity.workers = self.similarity.workers.clamp(1, 16);
if !self.similarity.minimum_score.is_finite() {
self.similarity.minimum_score = default_similarity_minimum_score();
}
self.similarity.minimum_score = self.similarity.minimum_score.clamp(0.0, 1.0);
self.similarity.max_tracks_per_artist = self.similarity.max_tracks_per_artist.clamp(1, 50);
self
}
}
fn default_volume() -> u8 {
80
}
fn default_similarity_model() -> String {
"discogs-effnet-bsdynamic-1".to_string()
}
fn default_similarity_profile() -> String {
"furumi-full-track-v1".to_string()
}
fn default_similarity_workers() -> usize {
std::thread::available_parallelism()
.map(|count| (count.get() / 2).clamp(1, 4))
.unwrap_or(1)
}
fn default_similarity_minimum_score() -> f32 {
0.70
}
fn default_similarity_max_tracks_per_artist() -> usize {
5
}
/// The historical permanent-download location, kept as the default for
/// backward compatibility with existing installations.
pub fn default_music_dir() -> PathBuf {
crate::config::project_dirs()
.map(|dirs| dirs.data_dir().join("federation-media"))
.unwrap_or_else(|| PathBuf::from("federation-media"))
}
pub fn load() -> (AppSettings, Option<String>) {
let Some(path) = settings_path() else {
return (AppSettings::default(), None);
};
match std::fs::read_to_string(&path) {
Ok(text) => match toml::from_str::<AppSettings>(&text) {
Ok(settings) => (settings.normalized(), None),
Err(err) => (
AppSettings::default(),
Some(format!("settings.toml is malformed: {err}")),
),
},
Err(err) if err.kind() == std::io::ErrorKind::NotFound => (AppSettings::default(), None),
Err(err) => (
AppSettings::default(),
Some(format!("settings.toml could not be read: {err}")),
),
}
}
pub fn save(settings: &AppSettings) -> Result<()> {
let path = settings_path().context("cannot determine the config directory")?;
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent)?;
}
std::fs::write(
&path,
toml::to_string_pretty(&settings.clone().normalized())?,
)
.with_context(|| format!("writing {}", path.display()))?;
Ok(())
}
fn settings_path() -> Option<std::path::PathBuf> {
crate::config::project_dirs().map(|dirs| dirs.config_dir().join("settings.toml"))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn settings_parse_and_normalize() {
let settings: AppSettings = toml::from_str(
r#"
volume = 150
[library]
hide_featured_only = true
"#,
)
.unwrap();
let settings = settings.normalized();
assert_eq!(settings.volume, 100);
assert!(settings.library.hide_featured_only);
assert_eq!(settings.library.source_mode, LibrarySourceMode::Global);
assert_eq!(settings.music_dir, default_music_dir());
assert_eq!(settings.similarity.minimum_score, 0.70);
assert_eq!(settings.similarity.max_tracks_per_artist, 5);
}
#[test]
fn similarity_search_policy_is_normalized_without_changing_the_profile() {
let mut settings = AppSettings::default();
let profile = settings.similarity.profile.clone();
settings.similarity.minimum_score = f32::NAN;
settings.similarity.max_tracks_per_artist = 0;
let settings = settings.normalized();
assert_eq!(settings.similarity.minimum_score, 0.70);
assert_eq!(settings.similarity.max_tracks_per_artist, 1);
assert_eq!(settings.similarity.profile, profile);
}
}
+4431
View File
File diff suppressed because it is too large. Load diff
@@ -0,0 +1 @@
{"type":"hello","group_id":"grp_1","profile":{"device_id":"tui_a","name":"TUI","client_version":"0.3.4","protocol_version":3,"endpoint_id":"e","endpoint_ticket":"t","revoked":false,"revoke_cutoff_seq":null,"updated_at_ms":5},"devices":[{"device_id":"tui_a","name":"TUI","client_version":"0.3.4","protocol_version":3,"endpoint_id":"e","endpoint_ticket":"t","revoked":false,"revoke_cutoff_seq":null,"updated_at_ms":5},{"device_id":"web_b","name":"TUI","client_version":"0.3.4","protocol_version":3,"endpoint_id":"e","endpoint_ticket":"t","revoked":false,"revoke_cutoff_seq":null,"updated_at_ms":5}],"vector":{"tui_a":12,"web_b":4},"ops":[{"op_id":"tui_a:1","origin_device_id":"tui_a","seq":1,"hlc_ms":1700000000001,"payload":{"kind":"track_like_set","content_id":"b3:1111111111111111111111111111111111111111111111111111111111111111","liked":true,"fed":{"item_id":"item","owner":"owner","title":"Song","artist_names":["A"],"featured_artist_names":[],"year":2001,"duration_seconds":180,"content_id":"b3:1111111111111111111111111111111111111111111111111111111111111111","release_title":"Album","track_number":1,"disc_number":1}}},{"op_id":"tui_a:2","origin_device_id":"tui_a","seq":2,"hlc_ms":1700000000002,"payload":{"kind":"playlist_created","playlist_id":"pl","title":"Mix"}},{"op_id":"tui_a:3","origin_device_id":"tui_a","seq":3,"hlc_ms":1700000000003,"payload":{"kind":"playlist_renamed","playlist_id":"pl","title":"Mix 2"}},{"op_id":"tui_a:4","origin_device_id":"tui_a","seq":4,"hlc_ms":1700000000004,"payload":{"kind":"playlist_track_added","playlist_id":"pl","content_id":"b3:1111111111111111111111111111111111111111111111111111111111111111","position":0,"fed":null}},{"op_id":"tui_a:5","origin_device_id":"tui_a","seq":5,"hlc_ms":1700000000005,"payload":{"kind":"playlist_track_removed","playlist_id":"pl","content_id":"b3:1111111111111111111111111111111111111111111111111111111111111111"}},{"op_id":"tui_a:6","origin_device_id":"tui_a","seq":6,"hlc_ms":1700000000006,"payload":{"kind":"playlist_deleted","playlist_id":"pl"}},{"op_id":"tui_a:7","origin_device_id":"tui_a","seq":7,"hlc_ms":1700000000007,"payload":{"kind":"device_profile_set","name":"TUI","client_version":"0.3.4","endpoint_ticket":"t","endpoint_id":"e"}},{"op_id":"tui_a:8","origin_device_id":"tui_a","seq":8,"hlc_ms":1700000000008,"payload":{"kind":"device_trusted","target_device_id":"web_b"}},{"op_id":"tui_a:9","origin_device_id":"tui_a","seq":9,"hlc_ms":1700000000009,"payload":{"kind":"device_revoked","target_device_id":"old","target_max_seq_seen":3}},{"op_id":"tui_a:10","origin_device_id":"tui_a","seq":10,"hlc_ms":1700000000010,"payload":{"kind":"playback_command","target_device_id":"web_b","command":{"kind":"set_state","state":{"queue":[{"id":7,"title":"Song","track_number":1,"disc_number":null,"duration_seconds":180.5,"artist_names":["A"],"featured_artist_names":["B"],"release_id":3,"release_title":"Album","release_year":2001,"file_path":"","content_id":"b3:1111111111111111111111111111111111111111111111111111111111111111","audio_format":"flac","audio_bitrate":900,"audio_sample_rate":44100,"audio_bit_depth":16,"file_size_bytes":12345,"play_count":2,"fed":{"item_id":"item","owner":"owner","title":"Song","artist_names":["A"],"featured_artist_names":[],"year":2001,"duration_seconds":180,"content_id":"b3:1111111111111111111111111111111111111111111111111111111111111111","release_title":"Album","track_number":1,"disc_number":1}},{"id":0,"title":"Remote","track_number":null,"disc_number":null,"duration_seconds":0.0,"artist_names":[],"featured_artist_names":[],"release_id":0,"release_title":"","release_year":null,"file_path":"","content_id":null,"audio_format":null,"audio_bitrate":null,"audio_sample_rate":null,"audio_bit_depth":null,"file_size_bytes":null,"play_count":0,"fed":null}],"queue_pos":1,"playing":true,"paused":false,"idle_since_ms":null,"position_secs":42.5,"volume":73,"shuffle":true,"repeat":"all"},"seek":true},"authority":{"version":1,"claim":{"counter":3,"issuer":"tui_a","owner":"tui_a"},"sequence":9}}},{"op_id":"tui_a:11","origin_device_id":"tui_a","seq":11,"hlc_ms":1700000000011,"payload":{"kind":"playback_command","target_device_id":"web_b","command":{"kind":"active_changed","active_device_id":"web_b","active_device_name":"WEB","state":{"queue":[{"id":7,"title":"Song","track_number":1,"disc_number":null,"duration_seconds":180.5,"artist_names":["A"],"featured_artist_names":["B"],"release_id":3,"release_title":"Album","release_year":2001,"file_path":"","content_id":"b3:1111111111111111111111111111111111111111111111111111111111111111","audio_format":"flac","audio_bitrate":900,"audio_sample_rate":44100,"audio_bit_depth":16,"file_size_bytes":12345,"play_count":2,"fed":{"item_id":"item","owner":"owner","title":"Song","artist_names":["A"],"featured_artist_names":[],"year":2001,"duration_seconds":180,"content_id":"b3:1111111111111111111111111111111111111111111111111111111111111111","release_title":"Album","track_number":1,"disc_number":1}},{"id":0,"title":"Remote","trackLine truncated
+137
View File
@@ -0,0 +1,137 @@
//! Cross-binary wire test. Run with scripts/test_device_interop.py; the other
//! endpoint is compiled from furumusic's real protocol types and player hub.
use super::*;
use tokio::io::AsyncWriteExt;
#[tokio::test]
#[ignore = "run scripts/test_device_interop.py to start both player test binaries"]
async fn localhost_web_peer() {
tokio::time::timeout(Duration::from_secs(30), async {
let dir = PathBuf::from(std::env::var("FURUMI_INTEROP_DIR").expect("interop runner"));
let address = loop {
if let Ok(address) = std::fs::read_to_string(dir.join("web-address")) {
break address;
}
tokio::time::sleep(Duration::from_millis(20)).await;
};
let mut stream = tokio::net::TcpStream::connect(address.trim())
.await
.unwrap();
let conn = Connection::open_in_memory().unwrap();
init_schema(&conn).unwrap();
let sync = DeviceSync {
_identity_lock: None,
conn: Arc::new(std::sync::Mutex::new(conn)),
library: Arc::new(Library::open(&dir.join("interop-library.sqlite3")).unwrap()),
event_tx: Default::default(),
playback: Default::default(),
podcasts: Default::default(),
};
let id = sync.ensure_identity().unwrap();
let (tx, mut events) = tokio::sync::mpsc::unbounded_channel();
sync.set_event_tx(tx);
sync.claim_playback(&id.device_id).unwrap();
sync.playback_tick(true, true).unwrap();
let mut state: PlaybackStateWire = serde_json::from_value(serde_json::json!({
"queue": [{ "id": 7, "title": "Interop track", "duration_seconds": 123.5,
"release_id": 1, "release_title": "Interop album", "artist_names": ["Interop artist"],
"content_id": "b3:0000000000000000000000000000000000000000000000000000000000000000" }],
"queue_pos": 0, "playing": true, "paused": false,
"position_secs": 42.5, "volume": 73, "shuffle": true, "repeat": "all"
}))
.unwrap();
for phase in 0..3 {
sync.publish_playback(PlaybackSnapshot {
device_id: id.device_id.clone(),
device_name: "TUI interop".into(),
active: true,
updated_at_ms: now_ms(),
state: state.clone(),
coordination: None,
});
let hello = WireMessage::Hello {
group_id: id.group_id.clone(),
profile: sync.own_profile("").unwrap(),
devices: vec![],
vector: BTreeMap::new(),
ops: vec![],
snapshot: SyncSnapshot::default(),
playback: sync.local_playback_snapshot_for(PROTOCOL_VERSION),
};
let mut bytes = serde_json::to_vec(&hello).unwrap();
bytes.push(b'\n');
stream.write_all(&bytes).await.unwrap();
let response: WireMessage =
serde_json::from_slice(
&music_dht::device_sync::read_line(&mut stream).await.unwrap(),
)
.unwrap();
let WireMessage::SyncResponse {
accepted: true,
playback: Some(snapshot),
ops,
..
} = response
else {
panic!("expected web response")
};
let web_id = snapshot.device_id.clone();
sync.apply_playback_snapshot(&web_id, snapshot).unwrap();
assert_eq!(ops.len(), 1);
let op = &ops[0];
// Production command adapter including durable fencing/deduplication.
sync.apply_op(op).unwrap();
sync.apply_op(op).unwrap();
let mut commands = Vec::new();
while let Ok(event) = events.try_recv() {
if let AppEvent::PlaybackCommand {
command,
authority,
origin,
} = event
{
assert!(sync.playback_command_is_current(&origin, &authority));
commands.push(command);
}
}
assert_eq!(commands.len(), 1, "one event even after duplicate delivery");
match commands.pop().unwrap() {
PlaybackCommand::ActiveChanged {
active_device_id,
state: next,
..
} => {
assert_eq!(
active_device_id,
if phase == 0 {
web_id.clone()
} else {
id.device_id.clone()
}
);
assert_eq!(next.position_secs, 42.5);
assert_eq!(next.queue, state.queue);
state = next;
}
PlaybackCommand::SetState { state: next, seek } => {
assert_eq!(phase, 2);
assert!(seek);
assert!(next.paused);
assert_eq!(next.position_secs, 87.0);
state = next;
}
}
assert_eq!(
sync.playback_tick(true, false).unwrap(),
Some(if phase == 0 {
web_id
} else {
id.device_id.clone()
})
);
}
stream.write_all(b"ok\n").await.unwrap();
})
.await
.expect("web/TUI exchange timed out");
}
File diff suppressed because it is too large. Load diff
+1449
View File
File diff suppressed because it is too large. Load diff
+576
View File
@@ -0,0 +1,576 @@
//! Golden wire-compatibility tests: the shared `music_dht::device_sync`
//! types this client now uses must serialize v3 content byte-for-byte like
//! the private copies of furumi-tui 0.3.x (kept verbatim in `legacy`
//! below), so 0.3.x clients and furumi-web 0.12.x keep interoperating.
use super::*;
/// Private wire types of furumi-tui 0.3.x (`src/devices.rs` before sync
/// v4), copied verbatim apart from visibility, `PartialEq` and doc comments.
#[allow(dead_code)]
pub(super) mod legacy {
use music_dht::device_sync::ListenEvent;
use music_dht::playback::CommandStamp;
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InviteWire {
pub v: u16,
#[serde(rename = "t")]
pub ticket: String,
#[serde(rename = "d")]
pub device_id: String,
#[serde(rename = "i")]
pub invite_id: String,
#[serde(rename = "s")]
pub secret: String,
#[serde(rename = "e")]
pub expires_at_ms: i64,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DeviceProfileWire {
pub device_id: String,
pub name: String,
pub client_version: String,
pub protocol_version: u16,
pub endpoint_id: String,
pub endpoint_ticket: String,
#[serde(default)]
pub revoked: bool,
#[serde(default)]
pub revoke_cutoff_seq: Option<i64>,
#[serde(default)]
pub updated_at_ms: i64,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SyncedFedTrack {
pub item_id: String,
pub owner: String,
pub title: String,
#[serde(default)]
pub artist_names: Vec<String>,
#[serde(default)]
pub featured_artist_names: Vec<String>,
pub year: Option<i32>,
pub duration_seconds: Option<i64>,
pub content_id: String,
pub release_title: Option<String>,
pub track_number: Option<i32>,
pub disc_number: Option<i32>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PlaybackTrack {
pub id: i64,
pub title: String,
pub track_number: Option<i32>,
pub disc_number: Option<i32>,
pub duration_seconds: f64,
#[serde(default)]
pub artist_names: Vec<String>,
#[serde(default)]
pub featured_artist_names: Vec<String>,
pub release_id: i64,
pub release_title: String,
pub release_year: Option<i32>,
#[serde(default)]
pub file_path: String,
pub content_id: Option<String>,
pub audio_format: Option<String>,
pub audio_bitrate: Option<i32>,
pub audio_sample_rate: Option<i32>,
pub audio_bit_depth: Option<i32>,
pub file_size_bytes: Option<i64>,
#[serde(default)]
pub play_count: i64,
#[serde(default)]
pub fed: Option<SyncedFedTrack>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum PlaybackRepeat {
#[default]
Off,
One,
All,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PlaybackStateWire {
#[serde(default)]
pub queue: Vec<PlaybackTrack>,
#[serde(default)]
pub queue_pos: usize,
pub playing: bool,
pub paused: bool,
#[serde(default)]
pub idle_since_ms: Option<i64>,
pub position_secs: f64,
#[serde(default)]
pub volume: u8,
pub shuffle: bool,
pub repeat: PlaybackRepeat,
}
pub type PlaybackSnapshot = music_dht::playback::Snapshot<PlaybackStateWire>;
pub type PlaybackCommand = music_dht::playback::Command<PlaybackStateWire>;
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SyncOpWire {
pub op_id: String,
pub origin_device_id: String,
pub seq: i64,
pub hlc_ms: i64,
pub payload: SyncOpPayload,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum SyncOpPayload {
TrackLikeSet {
content_id: String,
liked: bool,
#[serde(default)]
fed: Option<SyncedFedTrack>,
},
PlaylistCreated {
playlist_id: String,
title: String,
},
PlaylistRenamed {
playlist_id: String,
title: String,
},
PlaylistDeleted {
playlist_id: String,
},
PlaylistTrackAdded {
playlist_id: String,
content_id: String,
position: i64,
#[serde(default)]
fed: Option<SyncedFedTrack>,
},
PlaylistTrackRemoved {
playlist_id: String,
content_id: String,
},
DeviceProfileSet {
name: String,
client_version: String,
endpoint_ticket: String,
endpoint_id: String,
},
DeviceTrusted {
target_device_id: String,
},
DeviceRevoked {
target_device_id: String,
target_max_seq_seen: i64,
},
PlaybackCommand {
target_device_id: String,
command: PlaybackCommand,
#[serde(default)]
authority: Option<CommandStamp>,
},
ListenRecorded {
event: ListenEvent,
},
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct SyncSnapshot {
#[serde(default)]
pub likes: Vec<SnapshotLike>,
#[serde(default)]
pub unlikes: Vec<SnapshotLikeTombstone>,
#[serde(default)]
pub playlists: Vec<SnapshotPlaylist>,
#[serde(default)]
pub deleted_playlists: Vec<SnapshotPlaylistTombstone>,
#[serde(default)]
pub removed_playlist_items: Vec<SnapshotPlaylistItemTombstone>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SnapshotLike {
pub content_id: String,
pub hlc_ms: i64,
pub op_id: String,
#[serde(default)]
pub fed: Option<SyncedFedTrack>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SnapshotLikeTombstone {
pub content_id: String,
pub hlc_ms: i64,
pub op_id: String,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SnapshotPlaylist {
pub playlist_id: String,
pub title: String,
pub hlc_ms: i64,
pub op_id: String,
#[serde(default)]
pub items: Vec<SnapshotPlaylistItem>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SnapshotPlaylistTombstone {
pub playlist_id: String,
pub hlc_ms: i64,
pub op_id: String,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SnapshotPlaylistItem {
pub content_id: String,
pub position: i64,
pub hlc_ms: i64,
pub op_id: String,
#[serde(default)]
pub fed: Option<SyncedFedTrack>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SnapshotPlaylistItemTombstone {
pub playlist_id: String,
pub content_id: String,
pub hlc_ms: i64,
pub op_id: String,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum WireMessage {
PairRequest {
invite_id: String,
secret: String,
profile: DeviceProfileWire,
#[serde(default)]
group_id: Option<String>,
#[serde(default)]
group_active_devices: usize,
#[serde(default)]
devices: Vec<DeviceProfileWire>,
vector: BTreeMap<String, i64>,
ops: Vec<SyncOpWire>,
snapshot: SyncSnapshot,
#[serde(default)]
playback: Option<PlaybackSnapshot>,
},
PairResponse {
accepted: bool,
#[serde(default)]
pending: bool,
#[serde(default)]
error: Option<String>,
#[serde(default)]
group_id: Option<String>,
#[serde(default)]
profile: Option<DeviceProfileWire>,
#[serde(default)]
devices: Vec<DeviceProfileWire>,
#[serde(default)]
vector: BTreeMap<String, i64>,
#[serde(default)]
ops: Vec<SyncOpWire>,
#[serde(default)]
snapshot: SyncSnapshot,
#[serde(default)]
playback: Option<PlaybackSnapshot>,
},
Hello {
group_id: String,
profile: DeviceProfileWire,
devices: Vec<DeviceProfileWire>,
vector: BTreeMap<String, i64>,
ops: Vec<SyncOpWire>,
snapshot: SyncSnapshot,
#[serde(default)]
playback: Option<PlaybackSnapshot>,
},
SyncResponse {
accepted: bool,
#[serde(default)]
error: Option<String>,
#[serde(default)]
devices: Vec<DeviceProfileWire>,
#[serde(default)]
vector: BTreeMap<String, i64>,
#[serde(default)]
ops: Vec<SyncOpWire>,
#[serde(default)]
snapshot: SyncSnapshot,
#[serde(default)]
playback: Option<PlaybackSnapshot>,
},
}
}
const CONTENT_ID: &str = "b3:1111111111111111111111111111111111111111111111111111111111111111";
/// A v3 `hello` exercising every v3 operation kind, every snapshot section
/// and a coordinated playback snapshot (input order is irrelevant).
fn v3_hello_input() -> String {
let fed = serde_json::json!({
"item_id": "item", "owner": "owner", "title": "Song", "artist_names": ["A"],
"featured_artist_names": [], "year": 2001, "duration_seconds": 180,
"content_id": CONTENT_ID, "release_title": "Album", "track_number": 1, "disc_number": 1,
});
let track = serde_json::json!({
"id": 7, "title": "Song", "track_number": 1, "disc_number": null,
"duration_seconds": 180.5, "artist_names": ["A"], "featured_artist_names": ["B"],
"release_id": 3, "release_title": "Album", "release_year": 2001, "file_path": "",
"content_id": CONTENT_ID, "audio_format": "flac", "audio_bitrate": 900,
"audio_sample_rate": 44100, "audio_bit_depth": 16, "file_size_bytes": 12345,
"play_count": 2, "fed": fed,
});
let state = serde_json::json!({
"queue": [track, {"id": 0, "title": "Remote", "track_number": null, "disc_number": null,
"duration_seconds": 0.0, "release_id": 0, "release_title": "", "release_year": null,
"content_id": null, "audio_format": null, "audio_bitrate": null,
"audio_sample_rate": null, "audio_bit_depth": null, "file_size_bytes": null}],
"queue_pos": 1, "playing": true, "paused": false, "idle_since_ms": null,
"position_secs": 42.5, "volume": 73, "shuffle": true, "repeat": "all",
});
let claim = serde_json::json!({"counter": 3, "issuer": "tui_a", "owner": "tui_a"});
let stamp = serde_json::json!({"version": 1, "claim": claim, "sequence": 9});
let op = |seq: i64, payload: serde_json::Value| {
serde_json::json!({"op_id": format!("tui_a:{seq}"), "origin_device_id": "tui_a",
"seq": seq, "hlc_ms": 1_700_000_000_000i64 + seq, "payload": payload})
};
let profile = |id: &str| {
serde_json::json!({"device_id": id, "name": "TUI", "client_version": "0.3.4",
"protocol_version": 3, "endpoint_id": "e", "endpoint_ticket": "t",
"revoked": false, "revoke_cutoff_seq": null, "updated_at_ms": 5})
};
serde_json::json!({
"type": "hello",
"group_id": "grp_1",
"profile": profile("tui_a"),
"devices": [profile("tui_a"), profile("web_b")],
"vector": {"tui_a": 12, "web_b": 4},
"ops": [
op(1, serde_json::json!({"kind": "track_like_set", "content_id": CONTENT_ID, "liked": true, "fed": fed})),
op(2, serde_json::json!({"kind": "playlist_created", "playlist_id": "pl", "title": "Mix"})),
op(3, serde_json::json!({"kind": "playlist_renamed", "playlist_id": "pl", "title": "Mix 2"})),
op(4, serde_json::json!({"kind": "playlist_track_added", "playlist_id": "pl", "content_id": CONTENT_ID, "position": 0, "fed": null})),
op(5, serde_json::json!({"kind": "playlist_track_removed", "playlist_id": "pl", "content_id": CONTENT_ID})),
op(6, serde_json::json!({"kind": "playlist_deleted", "playlist_id": "pl"})),
op(7, serde_json::json!({"kind": "device_profile_set", "name": "TUI", "client_version": "0.3.4", "endpoint_ticket": "t", "endpoint_id": "e"})),
op(8, serde_json::json!({"kind": "device_trusted", "target_device_id": "web_b"})),
op(9, serde_json::json!({"kind": "device_revoked", "target_device_id": "old", "target_max_seq_seen": 3})),
op(10, serde_json::json!({"kind": "playback_command", "target_device_id": "web_b",
"command": {"kind": "set_state", "state": state, "seek": true}, "authority": stamp})),
op(11, serde_json::json!({"kind": "playback_command", "target_device_id": "web_b",
"command": {"kind": "active_changed", "active_device_id": "web_b", "active_device_name": "WEB", "state": state}})),
op(12, serde_json::json!({"kind": "listen_recorded", "event": {"listen_id": "l1",
"content_id": CONTENT_ID, "started_at_ms": 1, "listened_ms": 60000, "track_duration_ms": 180000,
"ended_reason": "finished", "track": {"title": "Song", "artist_names": ["A"], "featured_artist_names": [], "release_title": null}}})),
],
"snapshot": {
"likes": [{"content_id": CONTENT_ID, "hlc_ms": 1, "op_id": "tui_a:1", "fed": fed}],
"unlikes": [{"content_id": CONTENT_ID, "hlc_ms": 2, "op_id": "tui_a:2"}],
"playlists": [{"playlist_id": "pl", "title": "Mix", "hlc_ms": 3, "op_id": "tui_a:3",
"items": [{"content_id": CONTENT_ID, "position": 0, "hlc_ms": 4, "op_id": "tui_a:4", "fed": null}]}],
"deleted_playlists": [{"playlist_id": "gone", "hlc_ms": 5, "op_id": "tui_a:5"}],
"removed_playlist_items": [{"playlist_id": "pl", "content_id": CONTENT_ID, "hlc_ms": 6, "op_id": "tui_a:6"}],
},
"playback": {"device_id": "tui_a", "device_name": "TUI", "active": true, "updated_at_ms": 9,
"state": state, "coordination": {"version": 1, "claim": claim, "heartbeat": 4, "available": true, "playing": true}},
})
.to_string()
}
fn v3_other_inputs() -> Vec<String> {
vec![
r#"{"type":"sync_response","accepted":false,"error":"device is not trusted"}"#.into(),
r#"{"type":"pair_response","accepted":false,"pending":true,"error":"pairing pending"}"#
.into(),
serde_json::json!({"type": "pair_request", "invite_id": "i", "secret": "s",
"profile": {"device_id": "tui_a", "name": "TUI", "client_version": "0.3.4",
"protocol_version": 3, "endpoint_id": "e", "endpoint_ticket": "t"},
"vector": {}, "ops": [], "snapshot": {}})
.to_string(),
]
}
/// Parses `input` with the 0.3.x types and the shared types and checks
/// that both serialize to the same bytes, and that each side parses the
/// other's output.
fn assert_identical(input: &str) -> String {
let old: legacy::WireMessage = serde_json::from_str(input).unwrap();
let new: WireMessage = serde_json::from_str(input).unwrap();
let old_json = serde_json::to_string(&old).unwrap();
let new_json = serde_json::to_string(&new).unwrap();
assert_eq!(old_json, new_json);
assert_eq!(
serde_json::from_str::<legacy::WireMessage>(&new_json).unwrap(),
old
);
assert_eq!(serde_json::from_str::<WireMessage>(&old_json).unwrap(), new);
new_json
}
#[test]
fn v3_messages_serialize_like_furumi_tui_0_3() {
let hello = assert_identical(&v3_hello_input());
let golden = concat!(
env!("CARGO_MANIFEST_DIR"),
"/src/devices/fixtures/v3_hello.golden.json"
);
if std::env::var_os("FURUMI_BLESS_GOLDEN").is_some() {
// Only for a deliberate change of the v3 shape.
std::fs::write(golden, format!("{hello}\n")).unwrap();
}
assert_eq!(hello, std::fs::read_to_string(golden).unwrap().trim_end());
for input in v3_other_inputs() {
assert_identical(&input);
}
}
#[test]
fn music_queue_items_keep_their_v3_shape() {
let track = TrackItem {
id: 7,
title: "Song".into(),
track_number: Some(1),
disc_number: None,
duration_seconds: 180.5,
artists: vec![ArtistRef {
id: 1,
name: "A".into(),
}],
featured_artists: Vec::new(),
release_id: 3,
release_title: "Album".into(),
release_year: Some(2001),
file_path: "/Users/me/Music/song.flac".into(),
content_id: Some(CONTENT_ID.into()),
cover_path: None,
audio_format: Some("flac".into()),
audio_bitrate: Some(900),
audio_sample_rate: Some(44_100),
audio_bit_depth: Some(16),
file_size_bytes: Some(12_345),
play_count: 2,
fed: None,
podcast: None,
};
let wire = PlaybackTrack::from_track(&track);
let json = serde_json::to_string(&wire).unwrap();
assert!(
!json.contains("source"),
"music items carry no source: {json}"
);
let old: legacy::PlaybackTrack = serde_json::from_str(&json).unwrap();
assert_eq!(serde_json::to_string(&old).unwrap(), json);
}
#[test]
fn invites_from_older_clients_stay_readable() {
let old = legacy::InviteWire {
v: 1,
ticket: "ticket".into(),
device_id: "tui_a".into(),
invite_id: "inv".into(),
secret: "s3cr3t".into(),
expires_at_ms: 10,
};
let old_json = serde_json::to_string(&old).unwrap();
assert_eq!(
old_json,
r#"{"v":1,"t":"ticket","d":"tui_a","i":"inv","s":"s3cr3t","e":10}"#
);
let shared: InviteWire = serde_json::from_str(&old_json).unwrap();
assert_eq!(
shared.inviter_protocol_version(),
music_dht::device_sync::UNREPORTED_PROTOCOL_VERSION
);
assert_eq!(serde_json::to_string(&shared).unwrap(), old_json);
}
#[test]
fn v3_peers_cannot_parse_podcast_operations() {
// Why podcast operations must be gated: an unknown `kind` breaks the
// whole message for a 0.3.x peer, not one operation.
let mut hello: serde_json::Value = serde_json::from_str(&v3_hello_input()).unwrap();
hello["ops"].as_array_mut().unwrap().push(serde_json::json!({
"op_id": "tui_a:13", "origin_device_id": "tui_a", "seq": 13, "hlc_ms": 13,
"payload": {"kind": "podcast_share_set",
"podcast_id": music_dht::podcast::PodcastId::from_feed_url(
&music_dht::podcast::FeedUrl::parse("https://podcasts.example/feed.xml").unwrap()),
"shared": false, "generation": 1},
}));
assert!(serde_json::from_value::<legacy::WireMessage>(hello.clone()).is_err());
assert!(serde_json::from_value::<WireMessage>(hello).is_ok());
}
#[test]
fn v3_peers_would_drop_the_source_of_podcast_items() {
// Why podcast playback must be gated: older types ignore `source` and
// forward the episode as a broken music item.
let episode = crate::app::podcast_fixtures::episode_track(1)
.podcast
.unwrap();
let wire = PlaybackTrack::podcast_episode(episode);
let json = serde_json::to_string(&wire).unwrap();
assert!(json.contains(r#""source":{"kind":"podcast_episode""#));
let old: legacy::PlaybackTrack = serde_json::from_str(&json).unwrap();
let forwarded: PlaybackTrack =
serde_json::from_str(&serde_json::to_string(&old).unwrap()).unwrap();
assert_eq!(forwarded.source, None);
assert_eq!(forwarded.id, 0);
}
#[test]
fn version_reports_stay_readable_by_older_clients() {
let link = encode_invite(&InviteWire {
v: 1,
ticket: "ticket".into(),
device_id: "tui_a".into(),
invite_id: "inv".into(),
secret: "s3cr3t".into(),
expires_at_ms: 10,
protocol_version: Some(PROTOCOL_VERSION),
})
.unwrap();
let invite = parse_invite(&link).unwrap();
assert_eq!(invite.inviter_protocol_version(), PROTOCOL_VERSION);
let json = serde_json::to_string(&invite).unwrap();
assert!(
json.ends_with(&format!(r#","p":{PROTOCOL_VERSION}}}"#)),
"{json}"
);
// `p` is an unknown field for 0.3.x and is ignored there.
assert_eq!(
serde_json::from_str::<legacy::InviteWire>(&json)
.unwrap()
.invite_id,
"inv"
);
let announcement = SyncOpPayload::DeviceProfileSet {
name: "TUI".into(),
client_version: CLIENT_VERSION.into(),
endpoint_ticket: "t".into(),
endpoint_id: "e".into(),
protocol_version: Some(PROTOCOL_VERSION),
};
let json = serde_json::to_string(&announcement).unwrap();
assert!(json.ends_with(&format!(r#","protocol_version":{PROTOCOL_VERSION}}}"#)));
let old: legacy::SyncOpPayload = serde_json::from_str(&json).unwrap();
assert!(matches!(
old,
legacy::SyncOpPayload::DeviceProfileSet { .. }
));
}
+786
View File
@@ -0,0 +1,786 @@
//! The peer-to-peer audio protocol, wire compatible with furumi-fd.
//!
//! One byte stream per request: the requester sends one JSON line
//! ([`AudioRequest`]) and receives one JSON line ([`AudioResponseHeader`])
//! followed by the raw file bytes from the requested offset, unless the
//! requester asked for metadata only.
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::Instant;
use anyhow::{Context, Result};
use music_dht::{ByteStream, EndpointId, ItemId, ItemKind, MusicDhtService, StreamAcceptor};
use serde::{Deserialize, Serialize};
use tokio::io::{AsyncRead, AsyncReadExt, AsyncSeekExt, AsyncWriteExt};
use crate::library::Library;
/// ALPN of the audio streaming protocol (shared with furumi-fd).
pub const AUDIO_ALPN: &[u8] = b"furumi-fd/audio/1";
/// Version of the audio transfer stream protocol.
pub const AUDIO_PROTOCOL_VERSION: u16 = 1;
/// Maximum size of a JSON protocol line (request or response header).
const MAX_PROTOCOL_LINE: usize = 4096;
const STREAM_START_BUFFER_BYTES: u64 = 2 * 1024 * 1024;
#[derive(Debug, Clone, Copy)]
pub struct DownloadProgress {
pub stream_key: u64,
pub transport_phase: &'static str,
pub received: u64,
pub total: u64,
pub transport: Option<music_dht::ByteStreamConnectionStats>,
}
#[derive(Debug)]
pub struct StreamingStart {
pub reader: crate::streaming::GrowingFileReader,
pub mime_type: String,
}
#[derive(Debug, Serialize, Deserialize)]
struct AudioRequest {
/// Hex-encoded [`ItemId`] of the track.
item_id: String,
/// Byte offset to start streaming from (audio only; the cover, when
/// requested, is always sent whole).
offset: u64,
/// Ask the owner to send the cover art between the header and the
/// audio bytes. Default false keeps the wire layout compatible with
/// older peers in both directions.
#[serde(default)]
want_cover: bool,
/// Ask only for the response header with metadata and file facts.
/// Older peers ignore the field and may start streaming audio; the
/// requester simply drops the stream after reading the header.
#[serde(default)]
metadata_only: bool,
}
#[derive(Debug, Serialize, Deserialize)]
struct AudioResponseHeader {
ok: bool,
#[serde(default)]
error: Option<String>,
#[serde(default)]
mime_type: String,
#[serde(default)]
total_size: u64,
#[serde(default)]
offset: u64,
/// Full track metadata from the owner's database — richer and more
/// authoritative than whatever tags the file itself carries. Absent
/// when the peer predates the field (the header is extensible).
#[serde(default, skip_serializing_if = "Option::is_none")]
metadata: Option<TrackMetadata>,
/// Size of the cover-art segment sent between this header and the
/// audio bytes; 0 = no cover (not requested, not available).
#[serde(default)]
cover_size: u64,
#[serde(default)]
cover_mime: String,
/// Size of the main artist's image segment, sent after the cover and
/// before the audio; 0 = none. Governed by the same `want_cover` flag.
#[serde(default)]
artist_image_size: u64,
#[serde(default)]
artist_image_mime: String,
}
/// Covers above this size are skipped rather than transferred.
const MAX_COVER_BYTES: u64 = 16 * 1024 * 1024;
fn image_mime(path: &Path) -> &'static str {
match path
.extension()
.and_then(|e| e.to_str())
.unwrap_or_default()
.to_ascii_lowercase()
.as_str()
{
"png" => "image/png",
"webp" => "image/webp",
"gif" => "image/gif",
"bmp" => "image/bmp",
_ => "image/jpeg",
}
}
/// File extension for a received cover, from its mime type.
pub fn image_extension(mime: &str) -> &'static str {
match mime {
"image/png" => "png",
"image/webp" => "webp",
"image/gif" => "gif",
"image/bmp" => "bmp",
_ => "jpg",
}
}
/// Track metadata exchanged alongside the audio bytes.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct TrackMetadata {
#[serde(default)]
pub title: String,
#[serde(default)]
pub artists: Vec<String>,
#[serde(default)]
pub featured_artists: Vec<String>,
#[serde(default)]
pub album_artists: Vec<String>,
#[serde(default)]
pub release_title: String,
#[serde(default)]
pub release_type: Option<String>,
#[serde(default)]
pub year: Option<i32>,
#[serde(default)]
pub track_number: Option<i32>,
#[serde(default)]
pub disc_number: Option<i32>,
#[serde(default)]
pub duration_seconds: Option<f64>,
#[serde(default)]
pub audio_format: Option<String>,
#[serde(default)]
pub audio_bitrate: Option<i32>,
#[serde(default)]
pub audio_sample_rate: Option<i32>,
#[serde(default)]
pub audio_bit_depth: Option<i32>,
}
pub fn hex_encode(bytes: &[u8]) -> String {
bytes.iter().map(|b| format!("{b:02x}")).collect()
}
pub fn hex_decode_item_id(value: &str) -> Option<ItemId> {
if value.len() != 64 {
return None;
}
let mut bytes = [0u8; 32];
for (i, byte) in bytes.iter_mut().enumerate() {
*byte = u8::from_str_radix(&value[i * 2..i * 2 + 2], 16).ok()?;
}
Some(ItemId::from_bytes(bytes))
}
fn guess_mime(path: &Path) -> &'static str {
match path
.extension()
.and_then(|e| e.to_str())
.unwrap_or_default()
.to_ascii_lowercase()
.as_str()
{
"mp3" => "audio/mpeg",
"flac" => "audio/flac",
"ogg" | "oga" => "audio/ogg",
"opus" => "audio/opus",
"wav" => "audio/wav",
"m4a" | "mp4" | "alac" => "audio/mp4",
"aac" => "audio/aac",
"aiff" | "aif" => "audio/aiff",
_ => "application/octet-stream",
}
}
/// Extension for a downloaded file, from the mime type the peer reported.
fn extension_for_mime(mime: &str) -> &'static str {
match mime {
"audio/mpeg" => "mp3",
"audio/flac" | "audio/x-flac" => "flac",
"audio/ogg" => "ogg",
"audio/opus" => "opus",
"audio/wav" | "audio/x-wav" => "wav",
"audio/mp4" | "audio/x-m4a" => "m4a",
"audio/aac" => "aac",
"audio/aiff" => "aiff",
_ => "bin",
}
}
/// Best-effort audio format label for metadata previews, from the owner's
/// response mime type.
pub fn format_for_mime(mime: &str) -> Option<String> {
let extension = extension_for_mime(mime);
(extension != "bin").then(|| extension.to_string())
}
/// Reads one `\n`-terminated line, bounded by [`MAX_PROTOCOL_LINE`].
pub(super) async fn read_line<R: AsyncRead + Unpin>(reader: &mut R) -> Result<Vec<u8>> {
let mut line = Vec::new();
let mut byte = [0u8; 1];
loop {
let n = reader.read(&mut byte).await?;
if n == 0 {
anyhow::bail!("stream ended before the protocol line was complete");
}
if byte[0] == b'\n' {
return Ok(line);
}
line.push(byte[0]);
if line.len() > MAX_PROTOCOL_LINE {
anyhow::bail!("protocol line exceeds {MAX_PROTOCOL_LINE} bytes");
}
}
}
async fn write_line<W: AsyncWriteExt + Unpin>(
writer: &mut W,
value: &impl Serialize,
) -> Result<()> {
let mut line = serde_json::to_vec(value)?;
line.push(b'\n');
writer.write_all(&line).await?;
Ok(())
}
// ---------------------------------------------------------------------------
// Requesting side: download a track from its owner
// ---------------------------------------------------------------------------
/// Outcome of [`download_track`].
pub struct Downloaded {
pub path: PathBuf,
pub mime_type: String,
pub metadata: Option<TrackMetadata>,
/// Cover art (bytes, file extension) sent by the owner, if any.
pub cover: Option<(Vec<u8>, &'static str)>,
/// The main artist's image (bytes, file extension), if any.
pub artist_image: Option<(Vec<u8>, &'static str)>,
}
/// Header-only metadata fetched without downloading the audio bytes.
pub struct FetchedMetadata {
pub mime_type: String,
pub total_size: u64,
pub metadata: Option<TrackMetadata>,
}
/// Fetches the owner's response header for a track and closes the stream
/// before audio bytes are read.
pub async fn fetch_metadata(
service: &MusicDhtService,
owner: EndpointId,
item_id_hex: &str,
) -> Result<FetchedMetadata> {
let mut stream = service
.open_stream(owner, AUDIO_ALPN)
.await
.map_err(|err| anyhow::anyhow!("cannot reach the owner peer: {err}"))?;
write_line(
&mut stream.send,
&AudioRequest {
item_id: item_id_hex.to_string(),
offset: 0,
want_cover: false,
metadata_only: true,
},
)
.await?;
stream.send.finish()?;
let header: AudioResponseHeader = serde_json::from_slice(&read_line(&mut stream.recv).await?)
.context("malformed response header")?;
if !header.ok {
anyhow::bail!(
"peer refused the metadata: {}",
header.error.unwrap_or_else(|| "unknown error".to_string())
);
}
Ok(FetchedMetadata {
mime_type: header.mime_type,
total_size: header.total_size,
metadata: header.metadata,
})
}
pub async fn download_track_with_streaming<F>(
service: &MusicDhtService,
owner: EndpointId,
item_id_hex: &str,
dir: &Path,
stem: &str,
want_images: bool,
mut progress: F,
mut stream_start: Option<&mut (dyn FnMut(StreamingStart) + Send)>,
) -> Result<Downloaded>
where
F: FnMut(DownloadProgress) + Send,
{
let started = Instant::now();
let mut stream = service
.open_stream(owner, AUDIO_ALPN)
.await
.map_err(|err| anyhow::anyhow!("cannot reach the owner peer: {err}"))?;
let stream_key = super::stream_transport_key(&stream);
write_line(
&mut stream.send,
&AudioRequest {
item_id: item_id_hex.to_string(),
offset: 0,
want_cover: want_images,
metadata_only: false,
},
)
.await?;
stream.send.finish()?;
let header: AudioResponseHeader = serde_json::from_slice(&read_line(&mut stream.recv).await?)
.context("malformed response header")?;
if !header.ok {
anyhow::bail!(
"peer refused the stream: {}",
header.error.unwrap_or_else(|| "unknown error".to_string())
);
}
progress(DownloadProgress {
stream_key,
transport_phase: "download-open",
received: 0,
total: header.total_size,
transport: Some(stream.connection_stats()),
});
tracing::info!(
owner = %owner,
item_id = %item_id_hex,
audio_bytes = header.total_size,
cover_bytes = header.cover_size,
artist_image_bytes = header.artist_image_size,
want_images,
"federated audio stream opened"
);
// The image segments precede the audio bytes and are read regardless of
// the cache state — they sit first in the stream.
let mut read_image =
async |size: u64, mime: &str, what: &str| -> Result<Option<(Vec<u8>, &'static str)>> {
if size == 0 {
return Ok(None);
}
anyhow::ensure!(
size <= MAX_COVER_BYTES,
"{what} of {size} bytes exceeds the {MAX_COVER_BYTES} byte limit"
);
let mut bytes = vec![0u8; size as usize];
stream
.recv
.read_exact(&mut bytes)
.await
.with_context(|| format!("stream ended inside the {what} segment"))?;
Ok(Some((bytes, image_extension(mime))))
};
let cover = read_image(header.cover_size, &header.cover_mime, "cover").await?;
let artist_image = read_image(
header.artist_image_size,
&header.artist_image_mime,
"artist image",
)
.await?;
let extension = extension_for_mime(&header.mime_type);
let path = dir.join(format!("{stem}.{extension}"));
if let Ok(metadata) = tokio::fs::metadata(&path).await
&& metadata.len() == header.total_size
&& header.total_size > 0
{
// Audio already fully downloaded earlier; no need to fetch again.
progress(DownloadProgress {
stream_key,
transport_phase: "download-done",
received: header.total_size,
total: header.total_size,
transport: Some(stream.connection_stats()),
});
tracing::info!(
owner = %owner,
item_id = %item_id_hex,
bytes = header.total_size,
path = %path.display(),
"federated audio reused from cache"
);
return Ok(Downloaded {
path,
mime_type: header.mime_type,
metadata: header.metadata,
cover,
artist_image,
});
}
let temp_path = dir.join(format!(".{stem}.{extension}.part"));
let mut file = tokio::fs::File::create(&temp_path).await?;
let mut streaming = match stream_start.as_ref() {
Some(_) => match crate::streaming::growing_file(&temp_path) {
Ok((reader, writer)) => Some((Some(reader), writer, false)),
Err(err) => {
tracing::debug!(%err, path = %temp_path.display(), "streaming reader disabled");
None
}
},
None => None,
};
let stream_start_at = stream_start_buffer(header.total_size);
let mut received: u64 = 0;
let mut chunk = vec![0u8; 64 * 1024];
// quinn's inherent read returns None when the peer finished the stream.
while let Some(n) = stream.recv.read(&mut chunk).await? {
file.write_all(&chunk[..n]).await?;
received += n as u64;
if let Some((reader, writer, started)) = &mut streaming {
writer.add_available(n as u64);
if !*started
&& received >= stream_start_at
&& let (Some(reader), Some(callback)) = (reader.take(), stream_start.as_mut())
{
callback(StreamingStart {
reader,
mime_type: header.mime_type.clone(),
});
*started = true;
}
}
progress(DownloadProgress {
stream_key,
transport_phase: "download",
received,
total: header.total_size,
transport: None,
});
}
if let Some((reader, writer, started)) = &mut streaming {
if !*started
&& received > 0
&& let (Some(reader), Some(callback)) = (reader.take(), stream_start.as_mut())
{
callback(StreamingStart {
reader,
mime_type: header.mime_type.clone(),
});
*started = true;
}
writer.finish();
}
file.flush().await?;
drop(file);
if header.total_size > 0 && received != header.total_size {
let _ = tokio::fs::remove_file(&temp_path).await;
anyhow::bail!(
"download incomplete: got {received} of {} bytes",
header.total_size
);
}
tokio::fs::rename(&temp_path, &path).await?;
progress(DownloadProgress {
stream_key,
transport_phase: "download-done",
received,
total: header.total_size,
transport: Some(stream.connection_stats()),
});
let elapsed = started.elapsed();
let kib_per_sec = if elapsed.as_secs_f64() > 0.0 {
received as f64 / 1024.0 / elapsed.as_secs_f64()
} else {
0.0
};
tracing::info!(
owner = %owner,
item_id = %item_id_hex,
bytes = received,
elapsed_ms = elapsed.as_millis(),
kib_per_sec,
"federated audio downloaded"
);
Ok(Downloaded {
path,
mime_type: header.mime_type,
metadata: header.metadata,
cover,
artist_image,
})
}
fn stream_start_buffer(total_size: u64) -> u64 {
if total_size == 0 {
STREAM_START_BUFFER_BYTES
} else {
total_size.min(STREAM_START_BUFFER_BYTES)
}
}
// ---------------------------------------------------------------------------
// Serving side: answer audio requests from other peers
// ---------------------------------------------------------------------------
/// Finds the local track whose derived DHT item id matches `item_id`.
pub fn resolve_local_track_id(
library: &Library,
own: EndpointId,
item_id: ItemId,
) -> Result<Option<i64>> {
let export = library.federation_export()?;
for track in export.tracks {
let derived = ItemId::derive(&own, ItemKind::Track, &format!("track:{}", track.id));
if derived == item_id {
return Ok(Some(track.id));
}
}
Ok(None)
}
/// What the serving side needs to answer one audio request.
struct Served {
file_path: String,
metadata: TrackMetadata,
cover_path: Option<String>,
artist_image_path: Option<String>,
}
/// Resolves the item to the audio file, metadata and cover.
fn resolve_for_serving(
library: &Library,
own: EndpointId,
item_id: ItemId,
) -> Result<Option<Served>> {
let Some(track_id) = resolve_local_track_id(library, own, item_id)? else {
return Ok(None);
};
let Some(track) = library.tracks_by_ids(&[track_id])?.into_iter().next() else {
return Ok(None);
};
// Release type and album artists live on the release row.
let (release_type, album_artists) = match library.release(track.release_id) {
Ok(detail) => (
Some(detail.release_type),
detail.artists.iter().map(|a| a.name.clone()).collect(),
),
Err(_) => (None, Vec::new()),
};
let metadata = TrackMetadata {
title: track.title.clone(),
artists: track.artists.iter().map(|a| a.name.clone()).collect(),
featured_artists: track
.featured_artists
.iter()
.map(|a| a.name.clone())
.collect(),
album_artists,
release_title: track.release_title.clone(),
release_type,
year: track.release_year,
track_number: track.track_number,
disc_number: track.disc_number,
duration_seconds: Some(track.duration_seconds),
audio_format: track.audio_format.clone(),
audio_bitrate: track.audio_bitrate,
audio_sample_rate: track.audio_sample_rate,
audio_bit_depth: track.audio_bit_depth,
};
let artist_image_path = track
.artists
.first()
.and_then(|artist| library.artist_image(artist.id).ok().flatten());
Ok(Some(Served {
cover_path: track.cover_path.clone(),
artist_image_path,
file_path: track.file_path,
metadata,
}))
}
/// Runs the accept loop of the audio protocol until the acceptor closes.
/// Every track of the local library is downloadable by every peer of the
/// network — the libraries of all participants are equal.
pub async fn serve_peers(
mut acceptor: StreamAcceptor,
library: Arc<Library>,
own: EndpointId,
transport_stats: Arc<crate::federation::TransportStats>,
) {
while let Some(stream) = acceptor.accept().await {
let library = Arc::clone(&library);
let transport_stats = Arc::clone(&transport_stats);
tokio::spawn(async move {
let peer = stream.peer_id;
if let Err(err) = serve_one(stream, library, own, transport_stats).await {
tracing::warn!(peer = %peer, "audio stream failed: {err:#}");
}
});
}
}
async fn serve_one(
mut stream: ByteStream,
library: Arc<Library>,
own: EndpointId,
transport_stats: Arc<crate::federation::TransportStats>,
) -> Result<()> {
crate::federation::record_stream_transport(
&transport_stats,
"audio",
"inbound",
"open",
&stream,
);
let request: AudioRequest = serde_json::from_slice(&read_line(&mut stream.recv).await?)?;
tracing::info!(
peer = %stream.peer_id,
item = %request.item_id,
offset = request.offset,
"peer requested audio"
);
let resolved = match hex_decode_item_id(&request.item_id) {
Some(item_id) => {
let library = Arc::clone(&library);
match tokio::task::spawn_blocking(move || resolve_for_serving(&library, own, item_id))
.await
{
Ok(Ok(Some(found))) => Ok(found),
Ok(Ok(None)) => Err("track not found in the library".to_string()),
Ok(Err(err)) => Err(format!("library lookup failed: {err:#}")),
Err(err) => Err(format!("lookup task failed: {err}")),
}
}
None => Err("malformed item_id".to_string()),
};
let served = match resolved {
Ok(found) => found,
Err(message) => return refuse(stream, message).await,
};
let path = PathBuf::from(&served.file_path);
let mut file = match tokio::fs::File::open(&path).await {
Ok(file) => file,
Err(err) => return refuse(stream, format!("audio file is not readable: {err}")).await,
};
let total_size = file.metadata().await?.len();
let offset = request.offset.min(total_size);
if offset > 0 {
file.seek(std::io::SeekFrom::Start(offset)).await?;
}
// Images ride between the header and the audio, when asked for.
let (cover, artist_image) = if request.want_cover && !request.metadata_only {
(
load_cover(served.cover_path.as_deref()).await,
load_cover(served.artist_image_path.as_deref()).await,
)
} else {
(None, None)
};
write_line(
&mut stream.send,
&AudioResponseHeader {
ok: true,
error: None,
mime_type: guess_mime(&path).to_string(),
total_size,
offset,
metadata: Some(served.metadata),
cover_size: cover.as_ref().map_or(0, |(bytes, _)| bytes.len() as u64),
cover_mime: cover
.as_ref()
.map(|(_, mime)| mime.to_string())
.unwrap_or_default(),
artist_image_size: artist_image
.as_ref()
.map_or(0, |(bytes, _)| bytes.len() as u64),
artist_image_mime: artist_image
.as_ref()
.map(|(_, mime)| mime.to_string())
.unwrap_or_default(),
},
)
.await?;
if request.metadata_only {
stream.send.finish()?;
let _ = stream.send.stopped().await;
return Ok(());
}
let cover_bytes = cover.as_ref().map_or(0, |(bytes, _)| bytes.len() as u64);
let artist_image_bytes = artist_image
.as_ref()
.map_or(0, |(bytes, _)| bytes.len() as u64);
tracing::info!(
peer = %stream.peer_id,
item = %request.item_id,
audio_bytes = total_size.saturating_sub(offset),
cover_bytes,
artist_image_bytes,
want_images = request.want_cover,
"serving federated audio stream"
);
let started = Instant::now();
if let Some((bytes, _)) = &cover {
stream.send.write_all(bytes).await?;
}
if let Some((bytes, _)) = &artist_image {
stream.send.write_all(bytes).await?;
}
let audio_sent = tokio::io::copy(&mut file, &mut stream.send).await?;
stream.send.finish()?;
// Wait until the peer read everything (or gave up) before dropping the
// stream, otherwise the tail of the file is lost.
let _ = stream.send.stopped().await;
crate::federation::record_stream_transport(
&transport_stats,
"audio",
"inbound",
"done",
&stream,
);
let elapsed = started.elapsed();
let total_sent = cover_bytes + artist_image_bytes + audio_sent;
let kib_per_sec = if elapsed.as_secs_f64() > 0.0 {
total_sent as f64 / 1024.0 / elapsed.as_secs_f64()
} else {
0.0
};
tracing::info!(
peer = %stream.peer_id,
item = %request.item_id,
audio_bytes = audio_sent,
total_bytes = total_sent,
elapsed_ms = elapsed.as_millis(),
kib_per_sec,
"served federated audio stream"
);
Ok(())
}
/// Reads a cover image from disk, skipping unreadable or oversized files.
async fn load_cover(cover_path: Option<&str>) -> Option<(Vec<u8>, &'static str)> {
let path = PathBuf::from(cover_path?);
let size = tokio::fs::metadata(&path).await.ok()?.len();
if size == 0 || size > MAX_COVER_BYTES {
return None;
}
let bytes = tokio::fs::read(&path).await.ok()?;
Some((bytes, image_mime(&path)))
}
/// Sends a refusal header and waits until the peer read it.
async fn refuse(mut stream: ByteStream, message: String) -> Result<()> {
write_line(
&mut stream.send,
&AudioResponseHeader {
ok: false,
error: Some(message.clone()),
mime_type: String::new(),
total_size: 0,
offset: 0,
metadata: None,
cover_size: 0,
cover_mime: String::new(),
artist_image_size: 0,
artist_image_mime: String::new(),
},
)
.await?;
stream.send.finish()?;
let _ = stream.send.stopped().await;
anyhow::bail!("refused audio request: {message}");
}
+238
View File
@@ -0,0 +1,238 @@
//! Informational publication and observation of protocol versions.
use std::collections::BTreeMap;
use std::sync::{Arc, Mutex, MutexGuard};
use std::time::Duration;
use anyhow::{Context, Result};
pub use music_dht::capabilities::CAPABILITIES_ALPN;
use music_dht::capabilities::{
CAPABILITIES_PROTOCOL_VERSION, CapabilityManifest, CapabilityMessage, read_message,
write_message,
};
use music_dht::podcast_dht::PodcastDht;
use music_dht::{ByteStream, EndpointId, MusicDhtService, StreamAcceptor};
const PROBE_INTERVAL: Duration = Duration::from_secs(30);
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ProtocolVersions {
pub local: BTreeMap<String, u16>,
pub observed: BTreeMap<String, u16>,
pub observed_peers: usize,
pub newer: Vec<NewerProtocol>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NewerProtocol {
pub id: String,
pub local: u16,
pub observed: u16,
}
impl ProtocolVersions {
/// `podcast_dht`: whether this node runs the podcast-discovery overlay
/// (it is advertised only then).
pub fn snapshot(observed: &ObservedVersions, podcast_dht: bool) -> Self {
let local = local_manifest(podcast_dht).protocols;
let observed_versions = lock(&observed.versions).clone();
let newer = observed_versions
.iter()
.filter_map(|(id, remote)| {
let local_version = local.get(id)?;
(*remote > *local_version).then(|| NewerProtocol {
id: id.clone(),
local: *local_version,
observed: *remote,
})
})
.collect();
Self {
local,
observed: observed_versions,
observed_peers: lock(&observed.peers).len(),
newer,
}
}
}
#[derive(Default)]
pub struct ObservedVersions {
versions: Mutex<BTreeMap<String, u16>>,
peers: Mutex<BTreeMap<String, String>>,
}
/// This node's manifest. The podcast-discovery overlay is opt-in in FRID:
/// it is advertised only when this node serves it (`podcast_dht`), so
/// peers never dial an overlay that failed to open here.
fn local_manifest(podcast_dht: bool) -> CapabilityManifest {
let manifest = CapabilityManifest::frid("furumi", env!("CARGO_PKG_VERSION"))
.with_protocol("audio", super::audio::AUDIO_PROTOCOL_VERSION);
if podcast_dht {
manifest.with_podcast_dht()
} else {
manifest
}
}
pub async fn serve(mut acceptor: StreamAcceptor, podcast_dht: bool) {
while let Some(stream) = acceptor.accept().await {
tokio::spawn(async move {
if let Err(error) = serve_one(stream, podcast_dht).await {
tracing::debug!("capability stream failed: {error:#}");
}
});
}
}
async fn serve_one(mut stream: ByteStream, podcast_dht: bool) -> Result<()> {
let response = match read_message(&mut stream).await? {
CapabilityMessage::Get {
version: CAPABILITIES_PROTOCOL_VERSION,
} => CapabilityMessage::Manifest {
manifest: local_manifest(podcast_dht),
},
CapabilityMessage::Get { version } => CapabilityMessage::Error {
message: format!("unsupported capability protocol {version}"),
},
_ => CapabilityMessage::Error {
message: "expected capability request".to_string(),
},
};
write_message(&mut stream, &response).await?;
stream.send.finish()?;
let _ = tokio::time::timeout(Duration::from_secs(2), stream.send.stopped()).await;
Ok(())
}
/// Polls the manifests of known peers. With the podcast-discovery overlay
/// running, every manifest is handed to `PodcastDht::note_peer_capabilities`,
/// which stops dialing peers that do not serve the overlay.
pub async fn probe_loop(
service: Arc<MusicDhtService>,
observed: Arc<ObservedVersions>,
podcast_dht: Option<Arc<PodcastDht>>,
) {
let mut interval = tokio::time::interval(PROBE_INTERVAL);
loop {
interval.tick().await;
let peers = service
.connected_peers()
.into_iter()
.chain(
service
.known_peers()
.into_iter()
.map(|contact| contact.peer_id),
)
.collect::<std::collections::BTreeSet<_>>();
for peer in peers {
if let Err(error) = probe_peer(&service, peer, &observed, podcast_dht.as_deref()).await
{
tracing::trace!(%peer, "peer capability probe unavailable: {error:#}");
}
}
}
}
async fn probe_peer(
service: &MusicDhtService,
peer: EndpointId,
observed: &ObservedVersions,
podcast_dht: Option<&PodcastDht>,
) -> Result<()> {
let mut stream = service.open_stream(peer, CAPABILITIES_ALPN).await?;
write_message(
&mut stream,
&CapabilityMessage::Get {
version: CAPABILITIES_PROTOCOL_VERSION,
},
)
.await?;
stream.send.finish()?;
let response = tokio::time::timeout(Duration::from_secs(5), read_message(&mut stream))
.await
.context("capability request timed out")??;
let CapabilityMessage::Manifest { manifest } = response else {
anyhow::bail!("peer did not return a capability manifest");
};
manifest.validate()?;
if let Some(podcast_dht) = podcast_dht
&& let Err(error) = podcast_dht.note_peer_capabilities(peer, &manifest).await
{
tracing::debug!(%peer, "podcast DHT capability note failed: {error:#}");
}
{
let mut versions = lock(&observed.versions);
for (id, version) in manifest.protocols {
versions
.entry(id)
.and_modify(|current| *current = (*current).max(version))
.or_insert(version);
}
}
lock(&observed.peers).insert(peer.to_string(), manifest.application_version);
Ok(())
}
fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
mutex
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn local_manifest_lists_every_player_protocol() {
let manifest = local_manifest(true);
for id in [
"federation_net",
"ticket",
"rendezvous",
"music_dht",
"catalog",
"audio",
"similarity",
"similarity_dht",
"device_sync",
"jam",
"podcast_dht",
] {
assert!(manifest.protocols.contains_key(id), "missing {id}");
}
manifest.validate().unwrap();
assert!(manifest.supports_podcast_dht());
}
#[test]
fn podcast_discovery_is_advertised_only_when_it_runs() {
let manifest = local_manifest(false);
assert!(!manifest.supports_podcast_dht());
assert!(!manifest.protocols.contains_key("podcast_dht"));
manifest.validate().unwrap();
let observed = ObservedVersions::default();
assert!(
!ProtocolVersions::snapshot(&observed, false)
.local
.contains_key("podcast_dht")
);
assert!(
ProtocolVersions::snapshot(&observed, true)
.local
.contains_key("podcast_dht")
);
}
#[test]
fn snapshot_reports_only_strictly_newer_versions() {
let observed = ObservedVersions::default();
lock(&observed.versions).insert("music_dht".to_string(), 99);
lock(&observed.versions).insert("jam".to_string(), crate::jam::PROTOCOL_VERSION);
let snapshot = ProtocolVersions::snapshot(&observed, true);
assert_eq!(snapshot.newer.len(), 1);
assert_eq!(snapshot.newer[0].id, "music_dht");
}
}
+856
View File
@@ -0,0 +1,856 @@
//! The peer catalog protocol: one peer asks another for its library slice
//! of a single artist (releases with full tracklists plus featured
//! appearances), used to assemble a federated artist card.
//!
//! Wire shape on the `furumi-fd/catalog/1` ALPN: the requester sends one
//! JSON line ([`CatalogRequest`]) and finishes; the owner answers with one
//! JSON document ([`CatalogResponse`]) and finishes. All fields default, so
//! the shape is extensible like the audio protocol.
use std::collections::HashMap;
use std::sync::Arc;
use anyhow::{Context, Result};
pub use music_dht::catalog::{
CATALOG_ALPN, CatalogAppearance, CatalogArtist, CatalogArtistPreview, CatalogRelease,
CatalogTrack,
};
use music_dht::catalog::{CatalogImageHeader as ImageHeader, CatalogRequest, CatalogResponse};
use music_dht::{ByteStream, EndpointId, ItemKind, MusicDhtService, StreamAcceptor};
use tokio::io::AsyncReadExt;
use crate::library::Library;
/// Upper bound for one catalog response (thousands of tracks fit easily).
const MAX_CATALOG_BYTES: u64 = 4 * 1024 * 1024;
/// Images above this size are skipped rather than transferred.
const MAX_IMAGE_BYTES: u64 = 16 * 1024 * 1024;
// ---------------------------------------------------------------------------
// Serving side
// ---------------------------------------------------------------------------
/// Runs the catalog accept loop until the acceptor closes.
pub async fn serve_peers(
mut acceptor: StreamAcceptor,
library: Arc<Library>,
own: EndpointId,
transport_stats: Arc<crate::federation::TransportStats>,
) {
while let Some(stream) = acceptor.accept().await {
let library = Arc::clone(&library);
let transport_stats = Arc::clone(&transport_stats);
tokio::spawn(async move {
let peer = stream.peer_id;
if let Err(err) = serve_one(stream, library, own, transport_stats).await {
tracing::warn!(peer = %peer, "catalog request failed: {err:#}");
}
});
}
}
async fn serve_one(
mut stream: ByteStream,
library: Arc<Library>,
own: EndpointId,
transport_stats: Arc<crate::federation::TransportStats>,
) -> Result<()> {
crate::federation::record_stream_transport(
&transport_stats,
"catalog",
"inbound",
"open",
&stream,
);
let request: CatalogRequest =
serde_json::from_slice(&super::audio::read_line(&mut stream.recv).await?)?;
tracing::info!(
peer = %stream.peer_id,
artist = %request.artist,
want = request.want.as_deref().unwrap_or("catalog"),
"peer requested a catalog"
);
match request.want.as_deref() {
Some("artists") => {
let cursor = request.cursor.clone();
let limit = request.limit.unwrap_or(64).clamp(1, 200);
let response =
tokio::task::spawn_blocking(move || build_artist_slice(&library, cursor, limit))
.await?
.unwrap_or_else(|err| CatalogResponse {
ok: false,
error: Some(format!("artist slice failed: {err:#}")),
..CatalogResponse::default()
});
let payload = serde_json::to_vec(&response)?;
stream.send.write_all(&payload).await?;
}
None | Some("catalog") | Some("artist") => {
let response =
tokio::task::spawn_blocking(move || build_catalog(&library, own, &request.artist))
.await?
.unwrap_or_else(|err| CatalogResponse {
ok: false,
error: Some(format!("catalog lookup failed: {err:#}")),
..CatalogResponse::default()
});
let payload = serde_json::to_vec(&response)?;
stream.send.write_all(&payload).await?;
}
Some(want @ ("artist_image" | "release_cover")) => {
let want_cover = want == "release_cover";
let release = request.release.clone().unwrap_or_default();
let artist = request.artist.clone();
let path = tokio::task::spawn_blocking(move || -> Result<Option<String>> {
if want_cover {
library.release_cover_by_names(&artist, &release)
} else {
let Some(artist_id) = library.artist_id_by_name(&artist)? else {
return Ok(None);
};
library.artist_image(artist_id)
}
})
.await??;
serve_image(&mut stream, path.as_deref()).await?;
}
Some(other) => {
let response = CatalogResponse {
ok: false,
error: Some(format!("unknown request kind '{other}'")),
..CatalogResponse::default()
};
stream
.send
.write_all(&serde_json::to_vec(&response)?)
.await?;
}
}
stream.send.finish()?;
let _ = stream.send.stopped().await;
crate::federation::record_stream_transport(
&transport_stats,
"catalog",
"inbound",
"done",
&stream,
);
Ok(())
}
/// Streams one image file: header line, then the raw bytes.
async fn serve_image(stream: &mut ByteStream, path: Option<&str>) -> Result<()> {
let loaded = match path {
Some(path) => match tokio::fs::read(path).await {
Ok(bytes) if !bytes.is_empty() && bytes.len() as u64 <= MAX_IMAGE_BYTES => {
Some((bytes, image_mime_by_path(path)))
}
_ => None,
},
None => None,
};
let header = match &loaded {
Some((bytes, mime)) => ImageHeader {
ok: true,
error: None,
mime_type: (*mime).to_string(),
size: bytes.len() as u64,
},
None => ImageHeader {
ok: false,
error: Some("no image".to_string()),
..ImageHeader::default()
},
};
let mut line = serde_json::to_vec(&header)?;
line.push(b'\n');
stream.send.write_all(&line).await?;
if let Some((bytes, _)) = &loaded {
stream.send.write_all(bytes).await?;
}
Ok(())
}
fn image_mime_by_path(path: &str) -> &'static str {
match std::path::Path::new(path)
.extension()
.and_then(|e| e.to_str())
.unwrap_or_default()
.to_ascii_lowercase()
.as_str()
{
"png" => "image/png",
"webp" => "image/webp",
"gif" => "image/gif",
"bmp" => "image/bmp",
_ => "image/jpeg",
}
}
/// Builds this instance's library slice for `artist`.
fn build_catalog(library: &Library, own: EndpointId, artist: &str) -> Result<CatalogResponse> {
let Some(artist) = build_catalog_artist(library, own, artist)? else {
return Ok(CatalogResponse {
ok: false,
error: Some("artist not found in the library".to_string()),
..CatalogResponse::default()
});
};
Ok(CatalogResponse {
ok: true,
error: None,
artist: Some(artist),
..CatalogResponse::default()
})
}
fn build_artist_slice(
library: &Library,
cursor: Option<String>,
limit: usize,
) -> Result<CatalogResponse> {
let offset = cursor
.as_deref()
.and_then(|value| value.parse::<usize>().ok())
.unwrap_or(0);
let (artists, next_cursor) = library.artist_preview_slice(offset, limit)?;
Ok(CatalogResponse {
ok: true,
artists: artists
.into_iter()
.map(|artist| CatalogArtistPreview {
artist_key: artist.artist_key,
name: artist.name,
image_path: artist.image_path,
release_count: artist.release_count,
track_count: artist.track_count,
})
.collect(),
next_cursor,
..CatalogResponse::default()
})
}
/// Builds the successful payload for this instance's library slice.
pub(crate) fn build_catalog_artist(
library: &Library,
own: EndpointId,
artist: &str,
) -> Result<Option<CatalogArtist>> {
let Some(artist_id) = library.artist_id_by_name(artist)? else {
return Ok(None);
};
let detail = library.artist(artist_id)?;
let item_id_of = |track_id: i64| -> String {
super::audio::hex_encode(
music_dht::ItemId::derive(&own, ItemKind::Track, &format!("track:{track_id}"))
.as_bytes(),
)
};
let mut releases = Vec::new();
for card in &detail.releases {
let release = library.release(card.id)?;
releases.push(CatalogRelease {
title: release.title,
release_type: release.release_type,
year: release.year,
tracks: release
.tracks
.iter()
.map(|track| catalog_track(track, item_id_of(track.id)))
.collect(),
});
}
let mut appears_on = Vec::new();
for track in &detail.featured_tracks {
let release = library.release(track.release_id)?;
appears_on.push(CatalogAppearance {
release_title: track.release_title.clone(),
release_type: release.release_type,
year: track.release_year,
track: catalog_track(track, item_id_of(track.id)),
});
}
Ok(Some(CatalogArtist {
name: detail.name,
releases,
appears_on,
}))
}
fn catalog_track(track: &crate::library::models::TrackItem, item_id: String) -> CatalogTrack {
CatalogTrack {
title: track.title.clone(),
artists: track
.artists
.iter()
.map(|artist| artist.name.clone())
.collect(),
featured_artists: track
.featured_artists
.iter()
.map(|artist| artist.name.clone())
.collect(),
track_number: track.track_number,
disc_number: track.disc_number,
duration_seconds: (track.duration_seconds > 0.0).then_some(track.duration_seconds),
content_id: track.content_id.clone(),
item_id,
}
}
// ---------------------------------------------------------------------------
// Requesting side
// ---------------------------------------------------------------------------
/// Fetches one peer's catalog slice for `artist`.
pub async fn fetch_catalog(
service: &MusicDhtService,
owner: EndpointId,
artist: &str,
transport_stats: &Arc<crate::federation::TransportStats>,
) -> Result<CatalogArtist> {
let mut stream = service
.open_stream(owner, CATALOG_ALPN)
.await
.map_err(|err| anyhow::anyhow!("cannot reach the peer: {err}"))?;
crate::federation::record_stream_transport(
transport_stats,
"catalog",
"outbound",
"open",
&stream,
);
let mut line = serde_json::to_vec(&CatalogRequest {
artist: artist.to_string(),
want: None,
release: None,
cursor: None,
limit: None,
})?;
line.push(b'\n');
stream.send.write_all(&line).await?;
stream.send.finish()?;
let mut payload = Vec::new();
// The whole response is one JSON document, bounded by the byte cap.
tokio::io::AsyncReadExt::take(StreamReader(&mut stream), MAX_CATALOG_BYTES + 1)
.read_to_end(&mut payload)
.await?;
anyhow::ensure!(
payload.len() as u64 <= MAX_CATALOG_BYTES,
"catalog response exceeds {MAX_CATALOG_BYTES} bytes"
);
let response: CatalogResponse =
serde_json::from_slice(&payload).context("malformed catalog response")?;
crate::federation::record_stream_transport(
transport_stats,
"catalog",
"outbound",
"done",
&stream,
);
if !response.ok {
anyhow::bail!(
"peer refused the catalog: {}",
response
.error
.unwrap_or_else(|| "unknown error".to_string())
);
}
response.artist.context("empty catalog response")
}
/// Fetches a thin top-artist slice from one peer.
pub async fn fetch_artist_slice(
service: &MusicDhtService,
owner: EndpointId,
cursor: Option<&str>,
limit: usize,
transport_stats: &Arc<crate::federation::TransportStats>,
) -> Result<(Vec<CatalogArtistPreview>, Option<String>)> {
let mut stream = service
.open_stream(owner, CATALOG_ALPN)
.await
.map_err(|err| anyhow::anyhow!("cannot reach the peer: {err}"))?;
crate::federation::record_stream_transport(
transport_stats,
"catalog",
"outbound",
"open",
&stream,
);
let mut line = serde_json::to_vec(&CatalogRequest {
artist: String::new(),
want: Some("artists".to_string()),
release: None,
cursor: cursor.map(str::to_string),
limit: Some(limit),
})?;
line.push(b'\n');
stream.send.write_all(&line).await?;
stream.send.finish()?;
let mut payload = Vec::new();
tokio::io::AsyncReadExt::take(StreamReader(&mut stream), MAX_CATALOG_BYTES + 1)
.read_to_end(&mut payload)
.await?;
anyhow::ensure!(
payload.len() as u64 <= MAX_CATALOG_BYTES,
"catalog response exceeds {MAX_CATALOG_BYTES} bytes"
);
let response: CatalogResponse =
serde_json::from_slice(&payload).context("malformed catalog response")?;
crate::federation::record_stream_transport(
transport_stats,
"catalog",
"outbound",
"done",
&stream,
);
if !response.ok {
anyhow::bail!(
"peer refused the artist slice: {}",
response
.error
.unwrap_or_else(|| "unknown error".to_string())
);
}
Ok((response.artists, response.next_cursor))
}
/// Fetches an image (artist image or a release cover) from a peer over the
/// catalog protocol. `release: None` asks for the artist image. Returns the
/// raw bytes and a file extension, or None when the peer has no image.
pub async fn fetch_image(
service: &MusicDhtService,
owner: EndpointId,
artist: &str,
release: Option<&str>,
transport_stats: &Arc<crate::federation::TransportStats>,
) -> Result<Option<(Vec<u8>, &'static str)>> {
let mut stream = service
.open_stream(owner, CATALOG_ALPN)
.await
.map_err(|err| anyhow::anyhow!("cannot reach the peer: {err}"))?;
crate::federation::record_stream_transport(
transport_stats,
"catalog",
"outbound",
"open",
&stream,
);
let mut line = serde_json::to_vec(&CatalogRequest {
artist: artist.to_string(),
want: Some(if release.is_some() {
"release_cover".to_string()
} else {
"artist_image".to_string()
}),
release: release.map(str::to_string),
cursor: None,
limit: None,
})?;
line.push(b'\n');
stream.send.write_all(&line).await?;
stream.send.finish()?;
let header: ImageHeader =
serde_json::from_slice(&super::audio::read_line(&mut stream.recv).await?)
.context("malformed image header")?;
if !header.ok || header.size == 0 {
return Ok(None);
}
anyhow::ensure!(
header.size <= MAX_IMAGE_BYTES,
"image of {} bytes exceeds the {MAX_IMAGE_BYTES} byte limit",
header.size
);
let mut bytes = vec![0u8; header.size as usize];
stream
.recv
.read_exact(&mut bytes)
.await
.context("stream ended inside the image")?;
crate::federation::record_stream_transport(
transport_stats,
"catalog",
"outbound",
"done",
&stream,
);
let extension = match header.mime_type.as_str() {
"image/png" => "png",
"image/webp" => "webp",
"image/gif" => "gif",
"image/bmp" => "bmp",
_ => "jpg",
};
Ok(Some((bytes, extension)))
}
/// AsyncRead adapter over the receive half of a byte stream.
struct StreamReader<'a>(&'a mut ByteStream);
impl tokio::io::AsyncRead for StreamReader<'_> {
fn poll_read(
mut self: std::pin::Pin<&mut Self>,
cx: &mut std::task::Context<'_>,
buf: &mut tokio::io::ReadBuf<'_>,
) -> std::task::Poll<std::io::Result<()>> {
std::pin::Pin::new(&mut self.0.recv).poll_read(cx, buf)
}
}
// ---------------------------------------------------------------------------
// Aggregation
// ---------------------------------------------------------------------------
/// The assembled, deduplicated federated artist card.
#[derive(Debug, Clone, Default)]
pub struct FedArtistCard {
#[allow(dead_code, reason = "the open card is keyed by name in AppState")]
pub name: String,
/// This node's endpoint id, used to keep own tracks local when an open
/// card includes the local catalog alongside remote peers.
pub own_owner: Option<String>,
/// Peers whose catalogs contributed to the card.
pub peers: usize,
/// Every contributing peer (hex ids) — where images are fetched from.
pub owners: Vec<String>,
/// Local cache path of the artist image, streamed from a peer.
pub image_path: Option<String>,
pub releases: Vec<FedRelease>,
pub appears_on: Vec<FedAppearsOn>,
}
#[derive(Debug, Clone, Default)]
pub struct FedRelease {
pub title: String,
pub release_type: String,
pub year: Option<i32>,
/// Peers holding this release (hex ids).
pub owners: Vec<String>,
/// Local cache path of the cover, streamed from a peer.
pub cover_path: Option<String>,
pub tracks: Vec<FedCardTrack>,
}
#[derive(Debug, Clone, Default)]
pub struct FedAppearsOn {
pub release_title: String,
pub release_type: String,
pub year: Option<i32>,
pub track: FedCardTrack,
}
#[derive(Debug, Clone, Default)]
pub struct FedCardTrack {
pub title: String,
pub artists: Vec<String>,
pub featured_artists: Vec<String>,
pub track_number: Option<i32>,
pub disc_number: Option<i32>,
pub duration_seconds: Option<f64>,
pub content_id: Option<String>,
/// Every peer that can serve this track: (owner hex, item id hex).
/// Duplicates collapse into one row; all sources stay playable.
pub sources: Vec<(String, String)>,
}
/// Merges per-peer catalogs into one card: releases are keyed by normalized
/// title, tracks within a release by normalized title + track number; a
/// track present on several peers keeps every source.
pub fn merge_catalogs(name: &str, catalogs: Vec<(String, CatalogArtist)>) -> FedArtistCard {
let peers = catalogs.len();
let mut releases: Vec<FedRelease> = Vec::new();
let mut release_index: HashMap<String, usize> = HashMap::new();
let mut appears_on: Vec<FedAppearsOn> = Vec::new();
let mut appearance_index: HashMap<String, usize> = HashMap::new();
let mut card_owners: Vec<String> = Vec::new();
for (owner_hex, catalog) in catalogs {
if !card_owners.contains(&owner_hex) {
card_owners.push(owner_hex.clone());
}
for release in catalog.releases {
let release_key = music_dht::normalize_name(&release.title);
let slot = *release_index.entry(release_key).or_insert_with(|| {
releases.push(FedRelease {
title: release.title.clone(),
release_type: release.release_type.clone(),
year: None,
owners: Vec::new(),
cover_path: None,
tracks: Vec::new(),
});
releases.len() - 1
});
let merged = &mut releases[slot];
if !merged.owners.contains(&owner_hex) {
merged.owners.push(owner_hex.clone());
}
if merged.year.is_none() {
merged.year = release.year;
}
if merged.release_type.is_empty() {
merged.release_type = release.release_type.clone();
}
for track in release.tracks {
if track.item_id.is_empty() {
continue;
}
let existing = merged.tracks.iter_mut().find(|t| {
music_dht::normalize_name(&t.title) == music_dht::normalize_name(&track.title)
&& (t.track_number == track.track_number
|| t.track_number.is_none()
|| track.track_number.is_none())
});
match existing {
Some(t) => {
merge_card_track(t, &owner_hex, track);
}
None => merged.tracks.push(card_track(owner_hex.clone(), track)),
}
}
}
for appearance in catalog.appears_on {
if appearance.track.item_id.is_empty() {
continue;
}
let key = format!(
"{}:{}:{:?}",
music_dht::normalize_name(&appearance.release_title),
music_dht::normalize_name(&appearance.track.title),
appearance.track.track_number
);
let slot = *appearance_index.entry(key).or_insert_with(|| {
appears_on.push(FedAppearsOn {
release_title: appearance.release_title.clone(),
release_type: appearance.release_type.clone(),
year: appearance.year,
track: FedCardTrack::default(),
});
appears_on.len() - 1
});
let merged = &mut appears_on[slot];
if merged.release_type.is_empty() {
merged.release_type = appearance.release_type.clone();
}
if merged.year.is_none() {
merged.year = appearance.year;
}
if merged.track.title.is_empty() {
merged.track = card_track(owner_hex.clone(), appearance.track);
} else {
merge_card_track(&mut merged.track, &owner_hex, appearance.track);
}
}
}
for release in &mut releases {
release.tracks.sort_by_key(|t| {
(
t.disc_number.unwrap_or(1),
t.track_number.unwrap_or(i32::MAX),
)
});
}
appears_on.sort_by(|a, b| {
b.year
.unwrap_or(i32::MIN)
.cmp(&a.year.unwrap_or(i32::MIN))
.then_with(|| a.release_title.cmp(&b.release_title))
.then_with(|| {
a.track
.track_number
.unwrap_or(i32::MAX)
.cmp(&b.track.track_number.unwrap_or(i32::MAX))
})
.then_with(|| a.track.title.cmp(&b.track.title))
});
releases.sort_by(|a, b| {
b.year
.unwrap_or(i32::MIN)
.cmp(&a.year.unwrap_or(i32::MIN))
.then_with(|| a.title.cmp(&b.title))
});
FedArtistCard {
name: name.to_string(),
own_owner: None,
peers,
owners: card_owners,
image_path: None,
releases,
appears_on,
}
}
fn card_track(owner_hex: String, track: CatalogTrack) -> FedCardTrack {
FedCardTrack {
title: track.title,
artists: track.artists,
featured_artists: track.featured_artists,
track_number: track.track_number,
disc_number: track.disc_number,
duration_seconds: track.duration_seconds,
content_id: track.content_id,
sources: vec![(owner_hex, track.item_id)],
}
}
fn merge_card_track(target: &mut FedCardTrack, owner_hex: &str, track: CatalogTrack) {
if target.artists.is_empty() {
target.artists = track.artists;
}
if target.featured_artists.is_empty() {
target.featured_artists = track.featured_artists;
}
if target.track_number.is_none() {
target.track_number = track.track_number;
}
if target.disc_number.is_none() {
target.disc_number = track.disc_number;
}
if target.duration_seconds.is_none() {
target.duration_seconds = track.duration_seconds;
}
if target.content_id.is_none() {
target.content_id = track.content_id;
}
let source = (owner_hex.to_string(), track.item_id);
if !target.sources.contains(&source) {
target.sources.push(source);
}
}
#[cfg(test)]
mod tests {
use super::*;
fn track(title: &str, number: i32, item: &str) -> CatalogTrack {
CatalogTrack {
title: title.into(),
artists: vec!["Metallica".into()],
featured_artists: Vec::new(),
track_number: Some(number),
disc_number: None,
duration_seconds: Some(100.0),
content_id: None,
item_id: item.into(),
}
}
#[test]
fn merges_and_dedupes_across_peers() {
let catalog = |item_prefix: &str| CatalogArtist {
name: "Metallica".into(),
releases: vec![CatalogRelease {
title: "Black Album".into(),
release_type: "album".into(),
year: Some(1991),
tracks: vec![
track("Enter Sandman", 1, &format!("{item_prefix}1")),
track("Sad But True", 2, &format!("{item_prefix}2")),
],
}],
appears_on: Vec::new(),
};
let card = merge_catalogs(
"Metallica",
vec![
("peer-a".to_string(), catalog("a")),
("peer-b".to_string(), catalog("b")),
],
);
assert_eq!(card.peers, 2);
assert_eq!(card.releases.len(), 1);
let release = &card.releases[0];
assert_eq!(release.year, Some(1991));
assert_eq!(release.tracks.len(), 2);
// Both peers stay as sources of the deduplicated track.
assert_eq!(release.tracks[0].sources.len(), 2);
}
#[test]
fn merges_featured_appearances_across_peers() {
let mut featured = track("Guest Verse", 3, "a1");
featured.artists = vec!["Host".into()];
featured.featured_artists = vec!["Guest".into()];
let mut same_featured = featured.clone();
same_featured.item_id = "b1".into();
let card = merge_catalogs(
"Guest",
vec![
(
"peer-a".to_string(),
CatalogArtist {
name: "Guest".into(),
releases: Vec::new(),
appears_on: vec![CatalogAppearance {
release_title: "Host Album".into(),
release_type: "album".into(),
year: Some(2024),
track: featured,
}],
},
),
(
"peer-b".to_string(),
CatalogArtist {
name: "Guest".into(),
releases: Vec::new(),
appears_on: vec![CatalogAppearance {
release_title: "Host Album".into(),
release_type: "album".into(),
year: Some(2024),
track: same_featured,
}],
},
),
],
);
assert!(card.releases.is_empty());
assert_eq!(card.appears_on.len(), 1);
assert_eq!(card.appears_on[0].track.sources.len(), 2);
assert_eq!(card.appears_on[0].track.artists, vec!["Host"]);
assert_eq!(card.appears_on[0].track.featured_artists, vec!["Guest"]);
}
#[test]
fn merge_catalogs_sorts_releases_newest_first() {
let release = |title: &str, year: Option<i32>, item: &str| CatalogRelease {
title: title.into(),
release_type: "album".into(),
year,
tracks: vec![track("Song", 1, item)],
};
let card = merge_catalogs(
"Metallica",
vec![(
"peer-a".to_string(),
CatalogArtist {
name: "Metallica".into(),
releases: vec![
release("Old Album", Some(1991), "a1"),
release("New Album", Some(2024), "a2"),
release("Undated Album", None, "a3"),
],
appears_on: Vec::new(),
},
)],
);
let titles: Vec<&str> = card
.releases
.iter()
.map(|release| release.title.as_str())
.collect();
assert_eq!(titles, vec!["New Album", "Old Album", "Undated Album"]);
}
}
File diff suppressed because it is too large. Load diff
+367
View File
@@ -0,0 +1,367 @@
//! Furumi policy and local-index adapter for the shared similarity protocol.
//!
//! `music_dht::similarity` owns the versioned wire contract and framing. This
//! module owns application policy: consent, peer fan-out, local index access,
//! result conversion, deduplication, and ranking limits.
use std::collections::HashSet;
use std::sync::Arc;
use std::time::{Duration, Instant};
use anyhow::{Context as _, Result};
use futures_util::stream::{self, StreamExt as _};
use music_dht::similarity::{self as wire, SimilarityHit, SimilarityRequest, SimilarityResponse};
use music_dht::similarity_dht::SimilarityDht;
use music_dht::{
ByteStream, EndpointId, ItemId, ItemKind, MusicDhtService, PeerTicket, StreamAcceptor,
};
use crate::federation::{
FedSimilaritySearchResults, FedTrack, ScoredFedTrack, SimilaritySearchStats, TransportStats,
};
use crate::similarity::{Manager, QueryVector};
pub use music_dht::similarity::SIMILARITY_ALPN;
const INITIAL_QUERY_PEERS: usize = 16;
const MAX_QUERY_PEERS: usize = 48;
const QUERY_CONCURRENCY: usize = 8;
const QUERY_TIMEOUT: Duration = Duration::from_secs(5);
const ROUTING_TIMEOUT: Duration = Duration::from_secs(5);
const MAX_NEAR_DUPLICATE_SIGNATURE_DISTANCE: u32 = 8;
pub async fn serve_peers(
mut acceptor: StreamAcceptor,
similarity: Arc<Manager>,
own: EndpointId,
transport: Arc<TransportStats>,
) {
while let Some(stream) = acceptor.accept().await {
let similarity = Arc::clone(&similarity);
let transport = Arc::clone(&transport);
tokio::spawn(async move {
let peer = stream.peer_id;
if let Err(err) = serve_one(stream, similarity, own, transport).await {
tracing::warn!(peer = %peer, "similarity request failed: {err:#}");
}
});
}
}
async fn serve_one(
mut stream: ByteStream,
similarity: Arc<Manager>,
own: EndpointId,
transport: Arc<TransportStats>,
) -> Result<()> {
super::record_stream_transport(&transport, "similarity", "inbound", "open", &stream);
let request = wire::read_request(&mut stream).await?;
let response = if !similarity.network_allowed() {
SimilarityResponse::refused("similarity federation is disabled or has no privacy consent")?
} else {
let profile = request.profile_id;
let vector = request.vector;
let limit = request.limit;
let matches = tokio::task::spawn_blocking(move || {
similarity.search_vector_for_peer(&profile, &vector, limit)
})
.await
.context("local similarity task failed")
.and_then(|result| result);
match matches {
Ok(matches) => {
let hits = matches
.into_iter()
.filter_map(|found| {
let track = found.track;
let hit = SimilarityHit {
score: found.score,
item_id: super::audio::hex_encode(
ItemId::derive(
&own,
ItemKind::Track,
&format!("track:{}", track.id),
)
.as_bytes(),
),
title: track.title,
artist_names: track
.artists
.into_iter()
.map(|artist| artist.name)
.collect(),
featured_artist_names: track
.featured_artists
.into_iter()
.map(|artist| artist.name)
.collect(),
year: track.release_year,
duration_seconds: Some(track.duration_seconds.round() as i64),
content_id: track.content_id,
release_title: Some(track.release_title),
track_number: track.track_number,
disc_number: track.disc_number,
embedding_signature: Some(found.embedding_signature),
};
match hit.validate() {
Ok(()) => Some(hit),
Err(err) => {
tracing::debug!(%err, "invalid local similarity metadata skipped");
None
}
}
})
.collect();
SimilarityResponse::success(hits)?
}
Err(err) => {
SimilarityResponse::refused(format!("similarity query is unavailable: {err:#}"))?
}
}
};
wire::write_response(&mut stream, &response).await?;
stream.send.finish()?;
let _ = stream.send.stopped().await;
super::record_stream_transport(&transport, "similarity", "inbound", "done", &stream);
Ok(())
}
pub async fn search(
service: Arc<MusicDhtService>,
routing: Arc<SimilarityDht>,
query: QueryVector,
limit: usize,
minimum_score: f32,
transport: Arc<TransportStats>,
) -> Result<FedSimilaritySearchResults> {
let started = Instant::now();
let own = service.endpoint_id();
let routed = match tokio::time::timeout(
ROUTING_TIMEOUT,
routing.find_peers(&query.profile_id, &query.vector, MAX_QUERY_PEERS),
)
.await
{
Ok(Ok(peers)) => peers,
Err(_) => {
tracing::debug!("similarity DHT lookup timed out; using known peers");
Vec::new()
}
Ok(Err(error)) => {
tracing::debug!(%error, "similarity DHT lookup unavailable; using known peers");
Vec::new()
}
};
let mut seen = HashSet::new();
let mut peers: Vec<QueryPeer> = routed
.into_iter()
.filter_map(|ticket| {
let owner = ticket.endpoint_id();
(owner != own && seen.insert(owner)).then_some(QueryPeer {
owner,
ticket: Some(ticket),
})
})
.collect();
for peer in service
.connected_peers()
.into_iter()
.chain(service.known_peers().into_iter().map(|peer| peer.peer_id))
{
if peer != own && seen.insert(peer) {
peers.push(QueryPeer {
owner: peer,
ticket: None,
});
}
if peers.len() >= MAX_QUERY_PEERS {
break;
}
}
let query_signature = wire::embedding_signature(&query.vector)?;
let request = Arc::new(SimilarityRequest::new(
query.profile_id,
query.vector,
limit.clamp(1, wire::MAX_SIMILARITY_RESULTS),
)?);
let mut hits = Vec::new();
let initial = peers.len().min(INITIAL_QUERY_PEERS);
let responses = query_peers(
Arc::clone(&service),
&peers[..initial],
Arc::clone(&request),
Arc::clone(&transport),
)
.await;
let mut successful = 0usize;
let mut peers_queried = initial;
for response in responses {
match response {
Ok(peer_hits) => {
successful += 1;
hits.extend(peer_hits);
}
Err(err) => tracing::debug!(%err, "similarity peer query skipped"),
}
}
if initial < peers.len() && (hits.len() < limit || successful < initial.min(4)) {
peers_queried = peers.len();
for response in query_peers(
Arc::clone(&service),
&peers[initial..],
Arc::clone(&request),
Arc::clone(&transport),
)
.await
{
match response {
Ok(peer_hits) => hits.extend(peer_hits),
Err(err) => tracing::debug!(%err, "fallback similarity peer query skipped"),
}
}
}
hits.sort_by(|left, right| right.1.total_cmp(&left.1));
let mut dedup = HashSet::new();
let mut embedding_signatures = vec![query_signature];
let mut tracks = Vec::new();
for (track, score, embedding_signature) in hits {
if score < minimum_score {
break;
}
if query
.source_content_id
.as_deref()
.is_some_and(|source| track.content_id.as_deref() == Some(source))
{
continue;
}
let key = track
.content_id
.clone()
.unwrap_or_else(|| format!("{}:{}", track.owner, track.item_id));
if !dedup.insert(key) {
continue;
}
if embedding_signature.is_some_and(|candidate| {
embedding_signatures.iter().any(|existing| {
wire::signature_distance(&candidate, existing)
<= MAX_NEAR_DUPLICATE_SIGNATURE_DISTANCE
})
}) {
continue;
}
if let Some(signature) = embedding_signature {
embedding_signatures.push(signature);
}
tracks.push(ScoredFedTrack {
track,
score,
embedding_signature,
});
if tracks.len() >= limit.min(wire::MAX_SIMILARITY_RESULTS) {
break;
}
}
let artists = tracks
.iter()
.filter_map(|hit| hit.track.artist_names.first())
.map(|name| music_dht::normalize_name(name))
.filter(|name| !name.is_empty())
.collect::<HashSet<_>>()
.len();
let elapsed_ms = started.elapsed().as_millis().min(u128::from(u64::MAX)) as u64;
Ok(FedSimilaritySearchResults {
stats: SimilaritySearchStats {
tracks: tracks.len(),
artists,
peers_queried,
elapsed_ms,
},
tracks,
})
}
type PeerHits = Vec<(
FedTrack,
f32,
Option<[u8; wire::SIMILARITY_SIGNATURE_BYTES]>,
)>;
#[derive(Clone)]
struct QueryPeer {
owner: EndpointId,
ticket: Option<PeerTicket>,
}
async fn query_peers(
service: Arc<MusicDhtService>,
peers: &[QueryPeer],
request: Arc<SimilarityRequest>,
transport: Arc<TransportStats>,
) -> Vec<Result<PeerHits>> {
stream::iter(peers.iter().cloned().map(|peer| {
let service = Arc::clone(&service);
let request = Arc::clone(&request);
let transport = Arc::clone(&transport);
async move {
tokio::time::timeout(
QUERY_TIMEOUT,
query_peer(service, peer, &request, transport),
)
.await
.map_err(|_| anyhow::anyhow!("similarity peer timed out"))?
}
}))
.buffer_unordered(QUERY_CONCURRENCY)
.collect()
.await
}
async fn query_peer(
service: Arc<MusicDhtService>,
peer: QueryPeer,
request: &SimilarityRequest,
transport: Arc<TransportStats>,
) -> Result<PeerHits> {
let owner = peer.owner;
let mut stream = match peer.ticket {
Some(ticket) => service.open_stream_to(&ticket, SIMILARITY_ALPN).await,
None => service.open_stream(owner, SIMILARITY_ALPN).await,
}
.map_err(|err| anyhow::anyhow!("cannot reach similarity peer: {err}"))?;
super::record_stream_transport(&transport, "similarity", "outbound", "open", &stream);
let response = wire::exchange(&mut stream, request).await?;
super::record_stream_transport(&transport, "similarity", "outbound", "done", &stream);
anyhow::ensure!(
response.ok,
"peer refused similarity query: {}",
response.error.unwrap_or_default()
);
Ok(response
.hits
.into_iter()
.map(|hit| {
let score = hit.score;
let embedding_signature = hit.embedding_signature;
(
FedTrack {
item_id: hit.item_id,
owner: owner.to_string(),
own: false,
title: hit.title,
artist_names: hit.artist_names,
featured_artist_names: hit.featured_artist_names,
year: hit.year,
duration_seconds: hit.duration_seconds,
content_id: hit.content_id,
release_title: hit.release_title,
track_number: hit.track_number,
disc_number: hit.disc_number,
},
score,
embedding_signature,
)
})
.collect())
}
+169
View File
@@ -0,0 +1,169 @@
use super::*;
fn test_owner() -> EndpointId {
music_dht::SecretKey::from_bytes(&[7; 32]).public()
}
fn dht_track(main: &[&str], featured: &[&str]) -> LibraryItem {
let owner = test_owner();
LibraryItem {
id: music_dht::ItemId::derive(&owner, ItemKind::Track, "track:1"),
owner,
kind: ItemKind::Track,
name: "Guest Verse".into(),
normalized_name: music_dht::normalize_name("Guest Verse"),
artist_names: main.iter().map(|name| name.to_string()).collect(),
featured_artist_names: featured.iter().map(|name| name.to_string()).collect(),
year: Some(2024),
release_type: Some("album".into()),
release_title: Some("Host Album".into()),
track_number: Some(2),
disc_number: Some(1),
duration_seconds: Some(180.0),
content_id: Some(
"b3:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef".into(),
),
revision: 1,
deleted: false,
updated_at_ms: 0,
}
}
#[test]
fn dht_appearance_requires_explicit_featured_artist() {
let normalized = music_dht::normalize_name("Guest");
assert!(dht_appearance_hit(&dht_track(&["Guest"], &[]), &normalized, "Guest").is_none());
let hit = dht_appearance_hit(&dht_track(&["Host"], &["Guest"]), &normalized, "Guest").unwrap();
assert_eq!(hit.release_title, "Host Album");
assert_eq!(hit.release_type, "album");
assert_eq!(hit.year, Some(2024));
assert_eq!(hit.track.artists, vec!["Host"]);
assert_eq!(hit.track.featured_artists, vec!["Guest"]);
assert_eq!(hit.track.track_number, Some(2));
assert_eq!(hit.track.disc_number, Some(1));
}
#[test]
fn federation_search_ranks_exact_names_first() {
let normalized = music_dht::normalize_name("ежемесячные");
let mut artists = vec![
FedArtistHit {
name: "Booker".into(),
peers: 3,
},
FedArtistHit {
name: "Ежемесячные".into(),
peers: 1,
},
];
let mut tracks = vec![
FedTrack {
item_id: "a".into(),
owner: "peer-a".into(),
own: false,
title: "Гость".into(),
artist_names: vec!["Other".into()],
featured_artist_names: vec!["Ежемесячные".into()],
year: None,
duration_seconds: None,
content_id: None,
release_title: None,
track_number: None,
disc_number: None,
},
FedTrack {
item_id: "b".into(),
owner: "peer-b".into(),
own: false,
title: "Ежемесячные".into(),
artist_names: vec!["Other".into()],
featured_artist_names: Vec::new(),
year: None,
duration_seconds: None,
content_id: None,
release_title: None,
track_number: None,
disc_number: None,
},
];
rank_fed_search_results(&mut artists, &mut tracks, &normalized);
assert_eq!(artists[0].name, "Ежемесячные");
assert_eq!(tracks[0].title, "Ежемесячные");
}
#[test]
fn artist_catalog_discovery_uses_known_peers_without_dht_hits() {
let own = music_dht::SecretKey::from_bytes(&[8; 32]).public();
let peer = test_owner();
assert_eq!(
artist_catalog_owners(&[], "artist", own, [own, peer, peer]),
vec![peer]
);
// Unrelated records must not send the card request to their owners.
assert!(artist_catalog_owners(&[dht_track(&["Other"], &[])], "artist", own, []).is_empty());
}
#[test]
fn artist_catalog_discovery_prioritizes_matching_owners_and_bounds_fanout() {
let own = music_dht::SecretKey::from_bytes(&[8; 32]).public();
let peer = test_owner();
let known: Vec<_> = (10..60)
.map(|seed| music_dht::SecretKey::from_bytes(&[seed; 32]).public())
.collect();
for item in [
dht_track(&["Artist"], &[]),
dht_track(&["Host"], &["Artist"]),
] {
let owners = artist_catalog_owners(
&[item],
"artist",
own,
known.iter().copied().chain([own, peer]),
);
assert_eq!(owners.len(), 32);
assert_eq!(owners[0], peer);
assert!(!owners.contains(&own));
assert_eq!(
owners
.iter()
.collect::<std::collections::HashSet<_>>()
.len(),
owners.len()
);
}
}
/// The podcast-discovery overlay opens next to the other overlay caches; a
/// cache that cannot be opened only turns discovery off.
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn podcast_discovery_opens_or_turns_itself_off() {
async fn service(dir: &Path) -> Arc<MusicDhtService> {
let config = MusicDhtConfig::builder()
.data_dir(dir)
.network_id(NetworkId::from_name("furumi-tui-podcast-dht-open-test"))
.schema_independent_stream_protocol(PODCAST_DHT_ALPN)
.build()
.unwrap();
let (service, mut events) = MusicDhtService::start(config).await.unwrap();
tokio::spawn(async move { while events.recv().await.is_some() {} });
Arc::new(service)
}
let ok_dir = tempfile::tempdir().unwrap();
let ok = service(ok_dir.path()).await;
let opened = open_podcast_dht(&ok, ok_dir.path()).await;
assert!(opened.is_some());
assert!(ok_dir.path().join(PODCAST_DHT_CACHE_FILE).is_file());
drop(opened);
ok.shutdown().await.unwrap();
// A directory where the cache file belongs cannot be opened as SQLite.
let broken_dir = tempfile::tempdir().unwrap();
std::fs::create_dir(broken_dir.path().join(PODCAST_DHT_CACHE_FILE)).unwrap();
let broken = service(broken_dir.path()).await;
assert!(open_podcast_dht(&broken, broken_dir.path()).await.is_none());
broken.shutdown().await.unwrap();
}
+769
View File
@@ -0,0 +1,769 @@
//! Capability-based Jam playback control for independent federation peers.
use std::collections::{HashMap, HashSet, VecDeque};
use std::sync::{Arc, Mutex, MutexGuard};
use std::time::Duration;
use anyhow::{Context, Result};
use music_dht::{ByteStream, MusicDhtService, PeerTicket, StreamAcceptor};
use serde::{Deserialize, Serialize};
use tokio::sync::mpsc;
use crate::app::event::AppEvent;
use crate::devices::{PlaybackCommand, PlaybackSnapshot};
pub const JAM_ALPN: &[u8] = b"furumi/jam/1";
pub const PROTOCOL_VERSION: u16 = 1;
const MAX_LINE: usize = 8 * 1024 * 1024;
const MAX_COMMANDS: usize = 128;
const PARTICIPANT_TTL_MS: i64 = 30 * 60 * 1_000;
const POLL_INTERVAL: Duration = Duration::from_millis(500);
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum JamRole {
None,
Host,
Participant,
}
#[derive(Debug, Clone)]
pub struct JamStatus {
pub role: JamRole,
pub host_name: Option<String>,
pub invite: Option<String>,
pub participants: Vec<JamParticipant>,
pub connected: bool,
pub last_error: Option<String>,
}
impl Default for JamStatus {
fn default() -> Self {
Self {
role: JamRole::None,
host_name: None,
invite: None,
participants: Vec::new(),
connected: false,
last_error: None,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct JamParticipant {
pub participant_id: String,
pub name: String,
pub last_seen_ms: i64,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
struct JamInvite {
v: u16,
#[serde(rename = "t")]
ticket: String,
#[serde(rename = "j")]
jam_id: String,
#[serde(rename = "s")]
secret: String,
#[serde(rename = "d")]
host_device_id: String,
#[serde(rename = "n")]
host_name: String,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
struct JamCommand {
command_id: String,
participant_id: String,
command: PlaybackCommand,
sent_at_ms: i64,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
enum WireMessage {
Poll {
version: u16,
jam_id: String,
secret: String,
participant: JamParticipant,
#[serde(default)]
commands: Vec<JamCommand>,
},
Snapshot {
accepted: bool,
#[serde(default)]
error: Option<String>,
#[serde(default)]
acknowledged_command_ids: Vec<String>,
#[serde(default)]
playback: Option<PlaybackSnapshot>,
#[serde(default)]
participants: Vec<JamParticipant>,
host_time_ms: i64,
},
Leave {
version: u16,
jam_id: String,
secret: String,
participant_id: String,
},
}
#[derive(Default)]
struct HostState {
invite: Option<JamInvite>,
invite_uri: Option<String>,
playback: Option<PlaybackSnapshot>,
participants: HashMap<String, JamParticipant>,
seen_commands: HashSet<String>,
seen_order: VecDeque<String>,
}
struct JoinedState {
invite: JamInvite,
participant: JamParticipant,
pending: VecDeque<JamCommand>,
participants: Vec<JamParticipant>,
connected: bool,
last_error: Option<String>,
last_activity_ms: i64,
}
#[derive(Default)]
struct State {
host: HostState,
joined: Option<JoinedState>,
}
pub struct JamManager {
state: Mutex<State>,
event_tx: mpsc::UnboundedSender<AppEvent>,
}
impl JamManager {
pub fn new(event_tx: mpsc::UnboundedSender<AppEvent>) -> Arc<Self> {
Arc::new(Self {
state: Mutex::new(State::default()),
event_tx,
})
}
pub async fn create_or_regenerate(
&self,
service: Arc<MusicDhtService>,
host_device_id: String,
host_name: String,
) -> Result<String> {
let invite = JamInvite {
v: PROTOCOL_VERSION,
ticket: service.ticket().await?.to_string(),
jam_id: format!("jam_{}", random_hex(12)),
secret: random_hex(32),
host_device_id,
host_name,
};
let uri = encode_invite(&invite)?;
let mut state = lock(&self.state);
state.joined = None;
state.host = HostState {
invite: Some(invite),
invite_uri: Some(uri.clone()),
..HostState::default()
};
Ok(uri)
}
pub fn join(&self, uri: &str, participant_id: String, name: String) -> Result<()> {
let invite = parse_invite(uri)?;
let mut state = lock(&self.state);
state.host = HostState::default();
state.joined = Some(JoinedState {
invite,
participant: JamParticipant {
participant_id,
name,
last_seen_ms: now_ms(),
},
pending: VecDeque::new(),
participants: Vec::new(),
connected: false,
last_error: None,
last_activity_ms: now_ms(),
});
Ok(())
}
pub fn leave(&self) {
let mut state = lock(&self.state);
state.joined = None;
state.host = HostState::default();
}
pub fn status(&self) -> JamStatus {
let state = lock(&self.state);
if let Some(joined) = &state.joined {
return JamStatus {
role: JamRole::Participant,
host_name: Some(joined.invite.host_name.clone()),
invite: None,
participants: joined.participants.clone(),
connected: joined.connected,
last_error: joined.last_error.clone(),
};
}
if let Some(invite) = &state.host.invite {
return JamStatus {
role: JamRole::Host,
host_name: Some(invite.host_name.clone()),
invite: state.host.invite_uri.clone(),
participants: state.host.participants.values().cloned().collect(),
connected: true,
last_error: None,
};
}
JamStatus::default()
}
/// Publishes the host's playback to participants. Podcast episodes are
/// private: participants get opaque placeholders (`redact_for_jam`),
/// never their titles, feeds or URLs.
pub fn publish_host_playback(&self, snapshot: PlaybackSnapshot) {
let mut state = lock(&self.state);
if state.host.invite.is_some() {
state.host.playback = Some(PlaybackSnapshot {
state: music_dht::device_sync::redact_for_jam(snapshot.state),
..snapshot
});
}
}
pub fn submit_command(&self, command: PlaybackCommand) -> Result<()> {
let mut state = lock(&self.state);
let joined = state
.joined
.as_mut()
.context("this player is not controlling a Jam")?;
if joined.pending.len() >= MAX_COMMANDS {
joined.pending.pop_front();
}
joined.pending.push_back(JamCommand {
command_id: format!("cmd_{}", random_hex(16)),
participant_id: joined.participant.participant_id.clone(),
command,
sent_at_ms: now_ms(),
});
joined.last_activity_ms = now_ms();
Ok(())
}
async fn poll_once(&self, service: Arc<MusicDhtService>) -> Result<()> {
let (invite, participant, commands) = {
let state = lock(&self.state);
let joined = state.joined.as_ref().context("not joined")?;
(
joined.invite.clone(),
joined.participant.clone(),
joined.pending.iter().cloned().collect::<Vec<_>>(),
)
};
let ticket: PeerTicket = invite.ticket.parse().context("invalid Jam host ticket")?;
let peer = service.connect(ticket).await?;
let mut stream = service.open_stream(peer, JAM_ALPN).await?;
write_message(
&mut stream,
&WireMessage::Poll {
version: PROTOCOL_VERSION,
jam_id: invite.jam_id.clone(),
secret: invite.secret.clone(),
participant,
commands,
},
)
.await?;
stream.send.finish()?;
let response = read_message(&mut stream).await?;
let WireMessage::Snapshot {
accepted,
error,
acknowledged_command_ids,
playback,
participants,
..
} = response
else {
anyhow::bail!("unexpected Jam response");
};
anyhow::ensure!(
accepted,
"{}",
error.unwrap_or_else(|| "Jam refused".into())
);
{
let mut state = lock(&self.state);
let Some(joined) = state.joined.as_mut() else {
return Ok(());
};
if joined.invite.jam_id != invite.jam_id {
return Ok(());
}
let acknowledged = acknowledged_command_ids.into_iter().collect::<HashSet<_>>();
joined
.pending
.retain(|command| !acknowledged.contains(&command.command_id));
joined.participants = participants;
joined.connected = true;
joined.last_error = None;
joined.participant.last_seen_ms = now_ms();
if playback
.as_ref()
.is_some_and(|snapshot| snapshot.state.playing && !snapshot.state.paused)
{
joined.last_activity_ms = now_ms();
}
}
if let Some(playback) = playback {
let _ = self.event_tx.send(AppEvent::JamPlayback(playback));
}
let _ = self.event_tx.send(AppEvent::JamStatus(self.status()));
Ok(())
}
}
pub async fn serve_peers(mut acceptor: StreamAcceptor, manager: Arc<JamManager>) {
while let Some(stream) = acceptor.accept().await {
let manager = Arc::clone(&manager);
tokio::spawn(async move {
if let Err(err) = serve_one(stream, manager).await {
tracing::debug!("Jam stream failed: {err:#}");
}
});
}
}
async fn serve_one(mut stream: ByteStream, manager: Arc<JamManager>) -> Result<()> {
match read_message(&mut stream).await? {
WireMessage::Poll {
version,
jam_id,
secret,
mut participant,
commands,
} => {
let (accepted, error, acknowledged, playback, participants) = {
let mut state = lock(&manager.state);
let valid =
version == PROTOCOL_VERSION
&& state.host.invite.as_ref().is_some_and(|invite| {
invite.jam_id == jam_id && invite.secret == secret
});
if !valid {
(
false,
Some("invalid Jam capability".to_string()),
vec![],
None,
vec![],
)
} else {
let now = now_ms();
state.host.participants.retain(|_, row| {
now.saturating_sub(row.last_seen_ms) <= PARTICIPANT_TTL_MS
});
participant.last_seen_ms = now;
state
.host
.participants
.insert(participant.participant_id.clone(), participant);
let mut acknowledged = Vec::new();
for command in commands.into_iter().take(MAX_COMMANDS) {
acknowledged.push(command.command_id.clone());
if state.host.seen_commands.insert(command.command_id.clone()) {
state.host.seen_order.push_back(command.command_id.clone());
// Participants cannot add podcast episodes to the
// host queue; placeholders are mapped back by the
// host (`restore_jam_private_items`).
if music_dht::device_sync::jam_command_allowed(&command.command) {
let _ =
manager.event_tx.send(AppEvent::JamCommand(command.command));
} else {
tracing::info!("ignored a Jam command that adds podcast episodes");
}
}
}
while state.host.seen_order.len() > 4096 {
if let Some(id) = state.host.seen_order.pop_front() {
state.host.seen_commands.remove(&id);
}
}
(
true,
None,
acknowledged,
state.host.playback.clone(),
state.host.participants.values().cloned().collect(),
)
}
};
write_message(
&mut stream,
&WireMessage::Snapshot {
accepted,
error,
acknowledged_command_ids: acknowledged,
playback,
participants,
host_time_ms: now_ms(),
},
)
.await?;
stream.send.finish()?;
let _ = tokio::time::timeout(Duration::from_secs(2), stream.send.stopped()).await;
let _ = manager.event_tx.send(AppEvent::JamStatus(manager.status()));
}
WireMessage::Leave {
version,
jam_id,
secret,
participant_id,
} => {
let mut state = lock(&manager.state);
if version == PROTOCOL_VERSION
&& state
.host
.invite
.as_ref()
.is_some_and(|invite| invite.jam_id == jam_id && invite.secret == secret)
{
state.host.participants.remove(&participant_id);
}
drop(state);
let _ = manager.event_tx.send(AppEvent::JamStatus(manager.status()));
}
WireMessage::Snapshot { .. } => anyhow::bail!("unexpected Jam snapshot"),
}
Ok(())
}
pub async fn poll_loop(manager: Arc<JamManager>, service: Arc<MusicDhtService>) {
let mut interval = tokio::time::interval(POLL_INTERVAL);
loop {
interval.tick().await;
if manager.status().role != JamRole::Participant {
continue;
}
let expired = {
let state = lock(&manager.state);
state.joined.as_ref().is_some_and(|joined| {
now_ms().saturating_sub(joined.last_activity_ms) > PARTICIPANT_TTL_MS
})
};
if expired {
manager.leave();
let _ = manager.event_tx.send(AppEvent::JamStatus(manager.status()));
let _ = manager.event_tx.send(AppEvent::StatusMessage(
"Jam ended after 30 minutes without playback or commands".into(),
));
continue;
}
if let Err(err) = manager.poll_once(Arc::clone(&service)).await {
{
let mut state = lock(&manager.state);
if let Some(joined) = state.joined.as_mut() {
joined.connected = false;
joined.last_error = Some(format!("{err:#}"));
}
}
let _ = manager.event_tx.send(AppEvent::JamStatus(manager.status()));
}
}
}
async fn write_message(stream: &mut ByteStream, message: &WireMessage) -> Result<()> {
let mut bytes = serde_json::to_vec(message)?;
anyhow::ensure!(bytes.len() <= MAX_LINE, "Jam message is too large");
bytes.push(b'\n');
stream.send.write_all(&bytes).await?;
Ok(())
}
async fn read_message(stream: &mut ByteStream) -> Result<WireMessage> {
let mut bytes = Vec::new();
let mut byte = [0_u8; 1];
loop {
let read = stream.recv.read(&mut byte).await?;
if read.unwrap_or(0) == 0 || byte[0] == b'\n' {
break;
}
bytes.push(byte[0]);
anyhow::ensure!(bytes.len() <= MAX_LINE, "Jam message is too large");
}
anyhow::ensure!(!bytes.is_empty(), "empty Jam message");
Ok(serde_json::from_slice(&bytes)?)
}
fn encode_invite(invite: &JamInvite) -> Result<String> {
Ok(format!(
"frid://j/{}",
base64url_encode(&serde_json::to_vec(invite)?)
))
}
fn parse_invite(uri: &str) -> Result<JamInvite> {
let encoded = uri
.trim()
.strip_prefix("frid://j/")
.context("expected frid://j invite")?;
let invite: JamInvite = serde_json::from_slice(&base64url_decode(encoded)?)?;
anyhow::ensure!(
invite.v == PROTOCOL_VERSION,
"unsupported Jam invite version"
);
anyhow::ensure!(
!invite.ticket.is_empty()
&& !invite.jam_id.is_empty()
&& invite.secret.len() >= 16
&& !invite.host_device_id.is_empty(),
"incomplete Jam invite"
);
Ok(invite)
}
fn now_ms() -> i64 {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|duration| duration.as_millis() as i64)
.unwrap_or(0)
}
fn random_hex(bytes: usize) -> String {
use std::sync::atomic::{AtomicU64, Ordering};
static COUNTER: AtomicU64 = AtomicU64::new(1);
let seed = format!(
"{}:{}:{}",
now_ms(),
std::process::id(),
COUNTER.fetch_add(1, Ordering::Relaxed)
);
let hash = blake3::hash(seed.as_bytes()).to_hex().to_string();
hash[..(bytes * 2).min(hash.len())].to_string()
}
fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
mutex
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
}
fn base64url_encode(bytes: &[u8]) -> String {
const TABLE: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
let mut out = String::new();
for chunk in bytes.chunks(3) {
let b0 = chunk[0];
let b1 = chunk.get(1).copied().unwrap_or(0);
let b2 = chunk.get(2).copied().unwrap_or(0);
out.push(TABLE[(b0 >> 2) as usize] as char);
out.push(TABLE[(((b0 & 3) << 4) | (b1 >> 4)) as usize] as char);
if chunk.len() > 1 {
out.push(TABLE[(((b1 & 15) << 2) | (b2 >> 6)) as usize] as char);
}
if chunk.len() > 2 {
out.push(TABLE[(b2 & 63) as usize] as char);
}
}
out
}
fn base64url_decode(value: &str) -> Result<Vec<u8>> {
fn decode(byte: u8) -> Option<u8> {
match byte {
b'A'..=b'Z' => Some(byte - b'A'),
b'a'..=b'z' => Some(byte - b'a' + 26),
b'0'..=b'9' => Some(byte - b'0' + 52),
b'-' => Some(62),
b'_' => Some(63),
_ => None,
}
}
let bytes = value.as_bytes();
anyhow::ensure!(bytes.len() % 4 != 1, "invalid base64url Jam invite");
let mut out = Vec::with_capacity(bytes.len() * 3 / 4);
let mut i = 0;
while i < bytes.len() {
let a = decode(bytes[i]).context("invalid base64url Jam invite")?;
let b = decode(*bytes.get(i + 1).context("truncated Jam invite")?)
.context("invalid base64url Jam invite")?;
let c = bytes.get(i + 2).and_then(|byte| decode(*byte));
let d = bytes.get(i + 3).and_then(|byte| decode(*byte));
out.push((a << 2) | (b >> 4));
if let Some(c) = c {
out.push((b << 4) | (c >> 2));
if let Some(d) = d {
out.push((c << 6) | d);
}
}
i += 4;
}
Ok(out)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn invite_round_trips_and_is_separate_from_pairing() {
let invite = JamInvite {
v: PROTOCOL_VERSION,
ticket: "ticket".into(),
jam_id: "jam_test".into(),
secret: "0123456789abcdef".into(),
host_device_id: "dev_host".into(),
host_name: "Host".into(),
};
let uri = encode_invite(&invite).unwrap();
assert!(uri.starts_with("frid://j/"));
assert_eq!(parse_invite(&uri).unwrap().jam_id, "jam_test");
assert!(parse_invite("frid://i/abcd").is_err());
}
#[tokio::test]
async fn participant_receives_host_state_and_host_receives_command() {
let unique = random_hex(8);
let host_dir = std::env::temp_dir().join(format!("furumi-jam-host-{unique}"));
let guest_dir = std::env::temp_dir().join(format!("furumi-jam-guest-{unique}"));
std::fs::create_dir_all(&host_dir).unwrap();
std::fs::create_dir_all(&guest_dir).unwrap();
let network = music_dht::NetworkId::from_name(&format!("jam-test-{unique}"));
let host_config = music_dht::MusicDhtConfig::builder()
.data_dir(&host_dir)
.network_id(network)
.stream_protocol(JAM_ALPN)
.build()
.unwrap();
let guest_config = music_dht::MusicDhtConfig::builder()
.data_dir(&guest_dir)
.network_id(network)
.stream_protocol(JAM_ALPN)
.build()
.unwrap();
let (host_service, mut host_events) = music_dht::MusicDhtService::start(host_config)
.await
.unwrap();
let (guest_service, mut guest_events) = music_dht::MusicDhtService::start(guest_config)
.await
.unwrap();
let host_service = Arc::new(host_service);
let guest_service = Arc::new(guest_service);
let host_drain = tokio::spawn(async move { while host_events.recv().await.is_some() {} });
let guest_drain = tokio::spawn(async move { while guest_events.recv().await.is_some() {} });
let (host_tx, mut host_rx) = mpsc::unbounded_channel();
let (guest_tx, mut guest_rx) = mpsc::unbounded_channel();
let host = JamManager::new(host_tx);
let guest = JamManager::new(guest_tx);
let invite = host
.create_or_regenerate(Arc::clone(&host_service), "dev_host".into(), "Host".into())
.await
.unwrap();
guest
.join(&invite, "dev_guest".into(), "Guest".into())
.unwrap();
// The host plays a private podcast episode.
let episode = crate::app::podcast_fixtures::episode_track(1)
.podcast
.unwrap();
let playback_state = crate::devices::PlaybackStateWire {
queue: vec![crate::devices::PlaybackTrack::podcast_episode(
episode.clone(),
)],
queue_pos: 0,
playing: false,
paused: false,
idle_since_ms: Some(now_ms()),
position_secs: 0.0,
volume: 73,
shuffle: false,
repeat: crate::devices::PlaybackRepeat::Off,
playback_rate: None,
};
host.publish_host_playback(PlaybackSnapshot {
coordination: None,
device_id: "dev_host".into(),
device_name: "Host".into(),
active: true,
updated_at_ms: now_ms(),
state: playback_state.clone(),
});
let acceptor = host_service.stream_acceptor(JAM_ALPN).unwrap();
let server = tokio::spawn(serve_peers(acceptor, Arc::clone(&host)));
guest.poll_once(Arc::clone(&guest_service)).await.unwrap();
let playback = tokio::time::timeout(Duration::from_secs(3), async {
loop {
if let Some(AppEvent::JamPlayback(snapshot)) = guest_rx.recv().await {
break snapshot;
}
}
})
.await
.unwrap();
assert_eq!(playback.device_id, "dev_host");
assert_eq!(playback.state.volume, 73);
// Guests get an opaque placeholder: no title, feed or URL.
assert!(playback.state.queue[0].is_private_placeholder());
let seen = serde_json::to_string(&playback).unwrap();
assert!(!seen.contains(&episode.audio_url) && !seen.contains(&episode.episode_title));
// A guest cannot add an episode to the host's queue; its ordinary
// command (with the placeholder) still arrives.
guest
.submit_command(PlaybackCommand::SetState {
state: crate::devices::PlaybackStateWire {
queue: vec![crate::devices::PlaybackTrack::podcast_episode(episode)],
..playback_state.clone()
},
seek: false,
})
.unwrap();
guest
.submit_command(PlaybackCommand::SetState {
state: crate::devices::PlaybackStateWire {
paused: true,
..playback.state
},
seek: false,
})
.unwrap();
guest.poll_once(Arc::clone(&guest_service)).await.unwrap();
let command = tokio::time::timeout(Duration::from_secs(3), async {
loop {
if let Some(AppEvent::JamCommand(command)) = host_rx.recv().await {
break command;
}
}
})
.await
.unwrap();
let PlaybackCommand::SetState {
state: received,
seek: false,
} = command
else {
panic!("expected the guest's set_state");
};
// The command that adds an episode was sent first; had it been
// forwarded, it would have arrived first.
assert!(received.paused);
assert!(received.queue[0].is_private_placeholder());
server.abort();
host_drain.abort();
guest_drain.abort();
host_service.shutdown().await.unwrap();
guest_service.shutdown().await.unwrap();
let _ = std::fs::remove_dir_all(host_dir);
let _ = std::fs::remove_dir_all(guest_dir);
}
}
+3
View File
@@ -0,0 +1,3 @@
//! Compatibility facade for the client-independent `furumi-library` crate.
pub use furumi_library::*;
+182 -11
View File
@@ -1,10 +1,20 @@
mod api;
mod app;
mod art;
mod config;
mod devices;
mod federation;
mod jam;
mod library;
mod media;
mod player;
mod podcasts;
mod share;
mod similarity;
mod status;
mod streaming;
mod ui;
mod updater;
mod visualizer;
use std::io;
@@ -14,14 +24,51 @@ use crossterm::event::{
PopKeyboardEnhancementFlags, PushKeyboardEnhancementFlags,
};
const HELP: &str = "\
Furumi — federated terminal music player
Usage:
furumi [OPTION]
Options:
-h, --help Show this help
-V, --version Show version
--status Print a one-line now-playing status
--status-json
Print now-playing status as JSON
tmux:
set -g status-right '#(furumi --status)'
";
fn main() -> Result<()> {
let args: Vec<_> = std::env::args_os().collect();
if args.iter().any(|arg| arg == "--help" || arg == "-h") {
print!("{HELP}");
return Ok(());
}
if args.iter().any(|arg| arg == "--version" || arg == "-V") {
println!("furumi {}", env!("CARGO_PKG_VERSION"));
return Ok(());
}
if args
.iter()
.any(|arg| arg == "--status" || arg == "--status-json")
{
return status::print(args.iter().any(|arg| arg == "--status-json"));
}
let mut startup_warning = None;
if let Err(err) = config::logging::init() {
startup_warning = Some(format!("logging disabled: {err:#}"));
}
capture_stderr();
// Restore stderr before main returns: Rust prints a returned error only
// after local guards have been dropped and the terminal has been restored.
let _stderr_capture = capture_stderr();
let (keymap, keymap_warning) = config::keymap::Keymap::load();
let startup_warning = keymap_warning.or(startup_warning);
// The keymap message may be an informational notice; keep both so a
// logging failure is not hidden behind it.
let startup_warning = app::join_status_messages(keymap_warning, startup_warning);
// The app (tokio + TUI) runs on a worker thread; the main thread stays
// dedicated to the OS media-key event loop — on macOS the system only
@@ -90,25 +137,46 @@ fn run_app(
/// every line into tracing — it lands in the Logs tab and the log file
/// instead of the screen.
#[cfg(unix)]
fn capture_stderr() {
struct StderrCapture {
original: std::os::fd::RawFd,
}
#[cfg(unix)]
impl Drop for StderrCapture {
fn drop(&mut self) {
// SAFETY: original is our owned duplicate, kept open for this scope.
unsafe {
libc::dup2(self.original, libc::STDERR_FILENO);
libc::close(self.original);
}
}
}
#[cfg(unix)]
fn capture_stderr() -> Option<StderrCapture> {
use std::io::BufRead as _;
use std::os::fd::FromRawFd as _;
let mut fds = [0i32; 2];
// SAFETY: plain pipe/dup2 syscalls on freshly created fds.
unsafe {
let original = libc::dup(libc::STDERR_FILENO);
if original == -1 {
return None;
}
let capture = StderrCapture { original };
if libc::pipe(fds.as_mut_ptr()) != 0 {
return;
return None;
}
let [read_fd, write_fd] = fds;
if libc::dup2(write_fd, libc::STDERR_FILENO) == -1 {
libc::close(read_fd);
libc::close(write_fd);
return;
return None;
}
libc::close(write_fd);
let reader = std::fs::File::from_raw_fd(read_fd);
std::thread::Builder::new()
let reader_thread = std::thread::Builder::new()
.name("stderr".to_string())
.spawn(move || {
for line in std::io::BufReader::new(reader).lines() {
@@ -117,13 +185,116 @@ fn capture_stderr() {
tracing::warn!(target: "stderr", "{line}");
}
}
})
.ok();
});
if reader_thread.is_err() {
return None;
}
Some(capture)
}
}
#[cfg(not(unix))]
fn capture_stderr() {}
#[cfg(windows)]
struct StderrCapture {
original: windows_sys::Win32::Foundation::HANDLE,
writer: windows_sys::Win32::Foundation::HANDLE,
}
#[cfg(windows)]
impl Drop for StderrCapture {
fn drop(&mut self) {
// SAFETY: original is borrowed from the process; writer is owned by
// this guard. Restoring the original also preserves shell redirection.
unsafe {
windows_sys::Win32::System::Console::SetStdHandle(
windows_sys::Win32::System::Console::STD_ERROR_HANDLE,
self.original,
);
windows_sys::Win32::Foundation::CloseHandle(self.writer);
}
}
}
#[cfg(windows)]
fn capture_stderr() -> Option<StderrCapture> {
use std::io::BufRead as _;
use std::os::windows::io::FromRawHandle as _;
use windows_sys::Win32::Foundation::{CloseHandle, INVALID_HANDLE_VALUE};
use windows_sys::Win32::System::Console::{GetStdHandle, STD_ERROR_HANDLE, SetStdHandle};
use windows_sys::Win32::System::Pipes::CreatePipe;
unsafe {
let original = GetStdHandle(STD_ERROR_HANDLE);
if original.is_null() || original == INVALID_HANDLE_VALUE {
return None;
}
let mut read = core::ptr::null_mut();
let mut write = core::ptr::null_mut();
if CreatePipe(&mut read, &mut write, core::ptr::null(), 0) == 0 {
return None;
}
if SetStdHandle(STD_ERROR_HANDLE, write) == 0 {
CloseHandle(read);
CloseHandle(write);
return None;
}
let capture = StderrCapture {
original,
writer: write,
};
let reader = std::fs::File::from_raw_handle(read);
let reader_thread = std::thread::Builder::new()
.name("stderr".to_string())
.spawn(move || {
for line in std::io::BufReader::new(reader).lines() {
let Ok(line) = line else { break };
if !line.trim().is_empty() {
tracing::warn!(target: "stderr", "{line}");
}
}
});
if reader_thread.is_err() {
return None;
}
Some(capture)
}
}
#[cfg(not(any(unix, windows)))]
fn capture_stderr() -> Option<()> {
None
}
#[cfg(test)]
mod stderr_tests {
#[test]
fn error_output_is_restored_after_capture() {
const CHILD: &str = "FURUMI_STDERR_CAPTURE_TEST";
if std::env::var_os(CHILD).is_some() {
{
let _capture = super::capture_stderr().expect("capture stderr");
}
eprintln!("furumi-test: visible error after terminal shutdown");
return;
}
// Run in another process: redirecting global stderr inside a parallel
// test suite would interfere with unrelated tests and panic reporting.
let output = std::process::Command::new(std::env::current_exe().unwrap())
.args([
"--exact",
"stderr_tests::error_output_is_restored_after_capture",
"--nocapture",
])
.env(CHILD, "1")
.output()
.unwrap();
assert!(output.status.success());
assert!(
String::from_utf8_lossy(&output.stderr)
.contains("furumi-test: visible error after terminal shutdown")
);
}
}
/// Kitty keyboard protocol, where supported, disambiguates Esc from alt-keys
/// and modifier combos. The flags are popped on exit and on panic — leaving
+52 -1
View File
@@ -99,9 +99,10 @@ fn create_controls() -> Option<MediaControls> {
#[cfg(not(target_os = "windows"))]
let hwnd = None;
let dbus_name = platform_dbus_name();
let config = PlatformConfig {
display_name: "Furumi",
dbus_name: "cy.hexor.furumi",
dbus_name: &dbus_name,
hwnd,
};
match MediaControls::new(config) {
@@ -113,6 +114,41 @@ fn create_controls() -> Option<MediaControls> {
}
}
/// MPRIS well-known names must be unique on the session bus. Developers often
/// run a checkout next to an installed Furumi, and souvlaki 0.8.3 reports a
/// duplicate name by panicking in its private service thread. Ratatui's global
/// panic hook then restores the terminal even though the app thread is still
/// alive, leaving a frozen UI in canonical/echo mode.
///
/// Give every Unix MPRIS instance its own valid bus-name component. Other
/// backends ignore `dbus_name`, so retain the stable application identifier
/// there.
fn platform_dbus_name() -> String {
#[cfg(all(
unix,
not(any(target_os = "macos", target_os = "ios", target_os = "android"))
))]
{
mpris_dbus_name(std::process::id())
}
#[cfg(not(all(
unix,
not(any(target_os = "macos", target_os = "ios", target_os = "android"))
)))]
{
"cy.hexor.furumi".to_string()
}
}
#[cfg(all(
unix,
not(any(target_os = "macos", target_os = "ios", target_os = "android"))
))]
fn mpris_dbus_name(process_id: u32) -> String {
format!("cy.hexor.furumi.instance{process_id}")
}
/// An invisible top-level window owning the SMTC session. Created on the
/// main thread, which also pumps its messages in `pump_platform_events`.
#[cfg(target_os = "windows")]
@@ -217,3 +253,18 @@ fn pump_platform_events() {
#[cfg(not(any(target_os = "macos", target_os = "windows")))]
fn pump_platform_events() {}
#[cfg(test)]
mod tests {
#[cfg(all(
unix,
not(any(target_os = "macos", target_os = "ios", target_os = "android"))
))]
#[test]
fn mpris_names_are_distinct_between_processes() {
let first = super::mpris_dbus_name(41);
let second = super::mpris_dbus_name(42);
assert_eq!(first, "cy.hexor.furumi.instance41");
assert_ne!(first, second);
}
}
+455
View File
@@ -0,0 +1,455 @@
use std::sync::Arc;
use std::sync::atomic::{AtomicI16, AtomicU32, AtomicU64, AtomicUsize, Ordering};
use std::time::Duration;
use rodio::source::SeekError;
use rodio::{ChannelCount, Sample, SampleRate, Source};
const LEVEL_SCALE: f32 = 1_000_000.0;
const SCOPE_SAMPLES: usize = 256;
const SCOPE_SAMPLE_SCALE: f32 = i16::MAX as f32;
const TARGET_ANALYSIS_HZ: f32 = 30.0;
const TARGET_SCOPE_HZ: f32 = 240.0;
#[derive(Debug, Clone, Default)]
pub struct AudioAnalysisSnapshot {
pub sequence: u64,
pub energy: f64,
pub bass: f64,
pub mid: f64,
pub treble: f64,
pub beat: f64,
pub scope: Vec<f64>,
}
#[derive(Debug)]
pub struct AnalyzerShared {
sequence: AtomicU64,
energy: AtomicU32,
bass: AtomicU32,
mid: AtomicU32,
treble: AtomicU32,
beat: AtomicU32,
scope_write: AtomicUsize,
scope: Box<[AtomicI16]>,
}
impl Default for AnalyzerShared {
fn default() -> Self {
Self {
sequence: AtomicU64::new(0),
energy: AtomicU32::new(0),
bass: AtomicU32::new(0),
mid: AtomicU32::new(0),
treble: AtomicU32::new(0),
beat: AtomicU32::new(0),
scope_write: AtomicUsize::new(0),
scope: (0..SCOPE_SAMPLES)
.map(|_| AtomicI16::new(0))
.collect::<Vec<_>>()
.into_boxed_slice(),
}
}
}
impl AnalyzerShared {
pub fn clear(&self) {
self.energy.store(0, Ordering::Relaxed);
self.bass.store(0, Ordering::Relaxed);
self.mid.store(0, Ordering::Relaxed);
self.treble.store(0, Ordering::Relaxed);
self.beat.store(0, Ordering::Relaxed);
self.scope_write.store(0, Ordering::Relaxed);
for sample in self.scope.iter() {
sample.store(0, Ordering::Relaxed);
}
self.sequence.store(0, Ordering::Relaxed);
}
pub fn snapshot(&self) -> AudioAnalysisSnapshot {
let write = self.scope_write.load(Ordering::Relaxed);
let len = self.scope.len().max(1);
let scope = (0..self.scope.len())
.map(|offset| {
let index = (write + offset) % len;
f64::from(self.scope[index].load(Ordering::Relaxed)) / f64::from(i16::MAX)
})
.collect();
AudioAnalysisSnapshot {
sequence: self.sequence.load(Ordering::Relaxed),
energy: load_norm(&self.energy),
bass: load_norm(&self.bass),
mid: load_norm(&self.mid),
treble: load_norm(&self.treble),
beat: load_norm(&self.beat),
scope,
}
}
fn store_levels(&self, energy: f32, bass: f32, mid: f32, treble: f32, beat: f32) {
store_norm(&self.energy, energy);
store_norm(&self.bass, bass);
store_norm(&self.mid, mid);
store_norm(&self.treble, treble);
store_norm(&self.beat, beat);
self.sequence.fetch_add(1, Ordering::Relaxed);
}
fn push_scope(&self, sample: f32) {
let index = self.scope_write.fetch_add(1, Ordering::Relaxed) % self.scope.len();
let value = (sample.clamp(-1.0, 1.0) * SCOPE_SAMPLE_SCALE).round() as i16;
self.scope[index].store(value, Ordering::Relaxed);
}
}
pub struct AnalyzedSource<S> {
input: S,
shared: Arc<AnalyzerShared>,
state: AnalyzerState,
}
impl<S> AnalyzedSource<S>
where
S: Source,
{
pub fn new(input: S, shared: Arc<AnalyzerShared>) -> Self {
let channels = input.channels();
let sample_rate = input.sample_rate();
Self {
input,
shared,
state: AnalyzerState::new(channels, sample_rate),
}
}
}
impl<S> Iterator for AnalyzedSource<S>
where
S: Source,
{
type Item = Sample;
fn next(&mut self) -> Option<Self::Item> {
let sample = self.input.next()?;
self.state
.ensure_format(self.input.channels(), self.input.sample_rate());
self.state.accept_sample(sample as f32, &self.shared);
Some(sample)
}
fn size_hint(&self) -> (usize, Option<usize>) {
self.input.size_hint()
}
}
impl<S> Source for AnalyzedSource<S>
where
S: Source,
{
fn current_span_len(&self) -> Option<usize> {
self.input.current_span_len()
}
fn channels(&self) -> ChannelCount {
self.input.channels()
}
fn sample_rate(&self) -> SampleRate {
self.input.sample_rate()
}
fn total_duration(&self) -> Option<Duration> {
self.input.total_duration()
}
fn try_seek(&mut self, pos: Duration) -> Result<(), SeekError> {
let result = self.input.try_seek(pos);
if result.is_ok() {
self.shared.clear();
self.state.reset_filters();
}
result
}
}
#[derive(Debug)]
struct AnalyzerState {
channels: usize,
sample_rate: f32,
bass_alpha: f32,
mid_alpha: f32,
channel_index: usize,
frame_sum: f32,
frame_count: usize,
window_frames: usize,
scope_counter: usize,
scope_stride: usize,
low_bass: f32,
low_mid: f32,
full_sq: f32,
bass_sq: f32,
mid_sq: f32,
treble_sq: f32,
slow_energy: f32,
smooth_energy: f32,
smooth_bass: f32,
smooth_mid: f32,
smooth_treble: f32,
smooth_beat: f32,
}
impl AnalyzerState {
fn new(channels: ChannelCount, sample_rate: SampleRate) -> Self {
let mut state = Self {
channels: channels.get() as usize,
sample_rate: sample_rate.get() as f32,
bass_alpha: 0.0,
mid_alpha: 0.0,
channel_index: 0,
frame_sum: 0.0,
frame_count: 0,
window_frames: 0,
scope_counter: 0,
scope_stride: 0,
low_bass: 0.0,
low_mid: 0.0,
full_sq: 0.0,
bass_sq: 0.0,
mid_sq: 0.0,
treble_sq: 0.0,
slow_energy: 0.0,
smooth_energy: 0.0,
smooth_bass: 0.0,
smooth_mid: 0.0,
smooth_treble: 0.0,
smooth_beat: 0.0,
};
state.configure();
state
}
fn ensure_format(&mut self, channels: ChannelCount, sample_rate: SampleRate) {
let channels = channels.get() as usize;
let sample_rate = sample_rate.get() as f32;
if self.channels != channels || (self.sample_rate - sample_rate).abs() >= 1.0 {
self.channels = channels;
self.sample_rate = sample_rate;
self.configure();
self.reset_filters();
}
}
fn configure(&mut self) {
self.channels = self.channels.max(1);
self.sample_rate = self.sample_rate.max(1.0);
self.bass_alpha = lowpass_alpha(180.0, self.sample_rate);
self.mid_alpha = lowpass_alpha(2_400.0, self.sample_rate);
self.window_frames = (self.sample_rate / TARGET_ANALYSIS_HZ).round().max(256.0) as usize;
self.scope_stride = (self.sample_rate / TARGET_SCOPE_HZ).round().max(1.0) as usize;
}
fn reset_filters(&mut self) {
self.channel_index = 0;
self.frame_sum = 0.0;
self.frame_count = 0;
self.scope_counter = 0;
self.low_bass = 0.0;
self.low_mid = 0.0;
self.full_sq = 0.0;
self.bass_sq = 0.0;
self.mid_sq = 0.0;
self.treble_sq = 0.0;
self.slow_energy = 0.0;
self.smooth_energy = 0.0;
self.smooth_bass = 0.0;
self.smooth_mid = 0.0;
self.smooth_treble = 0.0;
self.smooth_beat = 0.0;
}
fn accept_sample(&mut self, sample: f32, shared: &AnalyzerShared) {
let sample = if sample.is_finite() {
sample.clamp(-1.5, 1.5)
} else {
0.0
};
self.frame_sum += sample;
self.channel_index += 1;
if self.channel_index < self.channels {
return;
}
let mono = self.frame_sum / self.channels as f32;
self.channel_index = 0;
self.frame_sum = 0.0;
self.accept_frame(mono, shared);
}
fn accept_frame(&mut self, sample: f32, shared: &AnalyzerShared) {
self.low_bass += self.bass_alpha * (sample - self.low_bass);
self.low_mid += self.mid_alpha * (sample - self.low_mid);
let bass = self.low_bass;
let mid = self.low_mid - self.low_bass;
let treble = sample - self.low_mid;
self.full_sq += sample * sample;
self.bass_sq += bass * bass;
self.mid_sq += mid * mid;
self.treble_sq += treble * treble;
self.frame_count += 1;
self.scope_counter += 1;
if self.scope_counter >= self.scope_stride {
self.scope_counter = 0;
shared.push_scope(sample);
}
if self.frame_count >= self.window_frames {
self.publish_window(shared);
}
}
fn publish_window(&mut self, shared: &AnalyzerShared) {
let frames = self.frame_count.max(1) as f32;
let energy = compress_rms((self.full_sq / frames).sqrt(), 7.5);
let bass = compress_rms((self.bass_sq / frames).sqrt(), 11.0);
let mid = compress_rms((self.mid_sq / frames).sqrt(), 15.0);
let treble = compress_rms((self.treble_sq / frames).sqrt(), 22.0);
if self.slow_energy == 0.0 {
self.slow_energy = energy;
} else {
self.slow_energy = self.slow_energy * 0.94 + energy * 0.06;
}
let beat_raw = ((energy - self.slow_energy * 1.18) * 5.5).clamp(0.0, 1.0);
self.smooth_energy = smooth_level(self.smooth_energy, energy, 0.35, 0.82);
self.smooth_bass = smooth_level(self.smooth_bass, bass, 0.30, 0.80);
self.smooth_mid = smooth_level(self.smooth_mid, mid, 0.35, 0.82);
self.smooth_treble = smooth_level(self.smooth_treble, treble, 0.28, 0.76);
self.smooth_beat = smooth_level(self.smooth_beat, beat_raw, 0.18, 0.70);
shared.store_levels(
self.smooth_energy,
self.smooth_bass,
self.smooth_mid,
self.smooth_treble,
self.smooth_beat,
);
self.full_sq = 0.0;
self.bass_sq = 0.0;
self.mid_sq = 0.0;
self.treble_sq = 0.0;
self.frame_count = 0;
}
}
fn lowpass_alpha(cutoff_hz: f32, sample_rate: f32) -> f32 {
1.0 - (-std::f32::consts::TAU * cutoff_hz / sample_rate.max(1.0)).exp()
}
fn compress_rms(rms: f32, scale: f32) -> f32 {
(1.0 - (-rms.max(0.0) * scale).exp()).clamp(0.0, 1.0)
}
fn smooth_level(previous: f32, next: f32, attack: f32, release: f32) -> f32 {
let keep = if next > previous { attack } else { release };
previous * keep + next * (1.0 - keep)
}
fn store_norm(target: &AtomicU32, value: f32) {
target.store(
(value.clamp(0.0, 1.0) * LEVEL_SCALE).round() as u32,
Ordering::Relaxed,
);
}
fn load_norm(source: &AtomicU32) -> f64 {
f64::from(source.load(Ordering::Relaxed)) / f64::from(LEVEL_SCALE)
}
#[cfg(test)]
mod tests {
use super::*;
struct TestSource {
samples: Vec<Sample>,
cursor: usize,
channels: ChannelCount,
sample_rate: SampleRate,
}
impl TestSource {
fn sine(frames: usize, channels: u16, sample_rate: u32, frequency: f32) -> Self {
let channels_count = channels.max(1);
let mut samples = Vec::with_capacity(frames * usize::from(channels_count));
for frame in 0..frames {
let time = frame as f32 / sample_rate as f32;
let sample = (std::f32::consts::TAU * frequency * time).sin() * 0.5;
for _ in 0..channels_count {
samples.push(sample as Sample);
}
}
Self {
samples,
cursor: 0,
channels: ChannelCount::new(channels_count).unwrap(),
sample_rate: SampleRate::new(sample_rate).unwrap(),
}
}
}
impl Iterator for TestSource {
type Item = Sample;
fn next(&mut self) -> Option<Self::Item> {
let sample = self.samples.get(self.cursor).copied()?;
self.cursor += 1;
Some(sample)
}
fn size_hint(&self) -> (usize, Option<usize>) {
let remaining = self.samples.len().saturating_sub(self.cursor);
(remaining, Some(remaining))
}
}
impl Source for TestSource {
fn current_span_len(&self) -> Option<usize> {
Some(self.samples.len().saturating_sub(self.cursor))
}
fn channels(&self) -> ChannelCount {
self.channels
}
fn sample_rate(&self) -> SampleRate {
self.sample_rate
}
fn total_duration(&self) -> Option<Duration> {
let frames = self.samples.len() / usize::from(self.channels.get());
Some(Duration::from_secs_f64(
frames as f64 / f64::from(self.sample_rate.get()),
))
}
}
#[test]
fn analyzed_source_publishes_levels_and_scope() {
let shared = Arc::new(AnalyzerShared::default());
let source = TestSource::sine(4_096, 2, 48_000, 110.0);
let analyzed = AnalyzedSource::new(source, Arc::clone(&shared));
for _ in analyzed {}
let snapshot = shared.snapshot();
assert!(snapshot.sequence > 0);
assert!(snapshot.energy > 0.0);
assert!(snapshot.bass > 0.0);
assert!(snapshot.scope.iter().any(|sample| sample.abs() > 0.001));
}
}
+438 -85
View File
@@ -4,16 +4,24 @@
//! through the callback given to `spawn` — this module knows nothing about
//! the UI or app state.
mod analyzer;
mod opus;
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::mpsc::{Receiver, RecvTimeoutError, Sender};
use std::time::Duration;
use rodio::{Decoder, DeviceSinkBuilder, Player, stream::MixerDeviceSink};
use stream_download::StreamDownload;
use stream_download::storage::temp::TempStorageProvider;
use rodio::{Decoder, DeviceSinkBuilder, Player, Source, stream::MixerDeviceSink};
pub type TrackReader = StreamDownload<TempStorageProvider>;
pub use analyzer::AudioAnalysisSnapshot;
pub trait TrackReadSeek: std::io::Read + std::io::Seek + Send + Sync {}
impl<T> TrackReadSeek for T where T: std::io::Read + std::io::Seek + Send + Sync {}
/// Playback sources are either ordinary files or growing streaming cache files.
pub type TrackReader = Box<dyn TrackReadSeek>;
/// Perceptual volume: cubic mapping from percent to linear amplitude, so
/// equal percent steps sound like equal loudness steps and low percentages
@@ -25,27 +33,50 @@ pub fn amplitude(percent: u8) -> f32 {
#[derive(Debug)]
pub enum PlayerEvent {
/// A newly requested source was decoded and handed to rodio.
Started,
/// A track played to its end. `has_next` is true when a prefetched
/// source was already queued and is now playing gaplessly.
TrackFinished {
has_next: bool,
},
Failed(String),
/// A seek was handled for the source started under `generation`
/// ([`Controller::source_generation`]); `result` says whether the source
/// actually moved to `position`.
Seeked {
generation: u64,
position: Duration,
result: Result<(), String>,
},
}
enum Command {
Play {
reader: Box<TrackReader>,
reader: TrackReader,
byte_len: Option<u64>,
mime_type: Option<String>,
seekable: bool,
volume: f32,
},
/// Play a source that was already opened, probed and positioned off
/// this thread (remote podcast streams, whose probing and seeking wait
/// on the network). Dropped unless `generation` is still current. It
/// starts paused if the latest pause/resume says so
/// ([`Controller::expect_source`]), not as it was when requested.
PlaySource {
source: DecodedSource,
volume: f32,
/// Where `source` was positioned before it was handed over.
start: Duration,
generation: u64,
},
/// Append the next track behind the current one without interrupting
/// playback — rodio switches sources back to back (gapless-ish).
Enqueue {
reader: Box<TrackReader>,
reader: TrackReader,
byte_len: Option<u64>,
},
TogglePause,
Pause,
Resume,
Stop,
@@ -58,6 +89,7 @@ enum Command {
pub struct Shared {
position_ms: AtomicU64,
paused: AtomicBool,
analysis: Arc<analyzer::AnalyzerShared>,
}
impl Shared {
@@ -68,43 +100,118 @@ impl Shared {
pub fn paused(&self) -> bool {
self.paused.load(Ordering::Relaxed)
}
pub fn audio_analysis(&self) -> AudioAnalysisSnapshot {
self.analysis.snapshot()
}
}
#[derive(Clone)]
pub struct Controller {
tx: Sender<Command>,
pub shared: Arc<Shared>,
playback_allowed: Arc<AtomicBool>,
/// Bumped by every start and stop; a source prepared in the background
/// plays only if no start or stop happened since it was requested.
generation: Arc<AtomicU64>,
/// The user's latest play/pause intent for a source still being
/// prepared: set by [`Controller::expect_source`], [`Controller::pause`]
/// and [`Controller::resume`], read when the source is handed over.
start_paused: Arc<AtomicBool>,
}
impl Controller {
/// Revoke the output at the audio thread boundary, including work queued
/// by background decoders before an ownership transfer.
pub fn set_playback_allowed(&self, allowed: bool) {
if self.playback_allowed.swap(allowed, Ordering::AcqRel) && !allowed {
self.stop();
}
}
/// The current source generation: capture it when starting to prepare a
/// source in the background and pass it to [`Controller::play_source`].
pub fn source_generation(&self) -> u64 {
self.generation.load(Ordering::SeqCst)
}
fn supersede(&self) {
self.generation.fetch_add(1, Ordering::SeqCst);
}
/// Whether a start or stop happened since `generation` was read; for
/// cancelling background preparation and reads of a superseded source.
pub fn superseded_check(&self, generation: u64) -> impl Fn() -> bool + Send + Sync + 'static {
let current = Arc::clone(&self.generation);
move || current.load(Ordering::SeqCst) != generation
}
/// A source is being prepared in the background and should start
/// paused or not. Pause and resume calls made before it is handed over
/// update this intent, so a pause pressed while it connects is kept.
pub fn expect_source(&self, paused: bool) {
self.start_paused.store(paused, Ordering::SeqCst);
}
/// Play a source decoded (and possibly positioned at `start`) outside
/// the audio thread, built with [`decode_source_with`]. The audio thread
/// drops it when another start or stop happened after `generation` was
/// read, so a slow stream never interrupts what the user chose since.
pub fn play_source(
&self,
source: DecodedSource,
volume: f32,
start: Duration,
generation: u64,
) {
let _ = self.tx.send(Command::PlaySource {
source,
volume,
start,
generation,
});
}
pub fn play(&self, reader: TrackReader, byte_len: Option<u64>, volume: f32) {
self.supersede();
self.start_paused.store(false, Ordering::SeqCst);
let _ = self.tx.send(Command::Play {
reader: Box::new(reader),
reader,
byte_len,
mime_type: None,
seekable: true,
volume,
});
}
pub fn play_stream(&self, reader: TrackReader, mime_type: Option<String>, volume: f32) {
self.supersede();
self.start_paused.store(false, Ordering::SeqCst);
let _ = self.tx.send(Command::Play {
reader,
byte_len: None,
mime_type,
seekable: false,
volume,
});
}
pub fn enqueue(&self, reader: TrackReader, byte_len: Option<u64>) {
let _ = self.tx.send(Command::Enqueue {
reader: Box::new(reader),
byte_len,
});
}
pub fn toggle_pause(&self) {
let _ = self.tx.send(Command::TogglePause);
let _ = self.tx.send(Command::Enqueue { reader, byte_len });
}
pub fn pause(&self) {
self.start_paused.store(true, Ordering::SeqCst);
let _ = self.tx.send(Command::Pause);
}
pub fn resume(&self) {
self.start_paused.store(false, Ordering::SeqCst);
let _ = self.tx.send(Command::Resume);
}
pub fn stop(&self) {
self.supersede();
let _ = self.tx.send(Command::Stop);
}
@@ -121,11 +228,40 @@ pub fn spawn(on_event: impl Fn(PlayerEvent) + Send + 'static) -> Controller {
let (tx, rx) = std::sync::mpsc::channel();
let shared = Arc::new(Shared::default());
let thread_shared = Arc::clone(&shared);
let playback_allowed = Arc::new(AtomicBool::new(true));
let thread_allowed = Arc::clone(&playback_allowed);
let generation = Arc::new(AtomicU64::new(0));
let thread_generation = Arc::clone(&generation);
let start_paused = Arc::new(AtomicBool::new(false));
let thread_start_paused = Arc::clone(&start_paused);
std::thread::Builder::new()
.name("audio".to_string())
.spawn(move || run(rx, thread_shared, on_event))
.spawn(move || {
run(
rx,
thread_shared,
thread_allowed,
Generations {
current: thread_generation,
start_paused: thread_start_paused,
},
on_event,
)
})
.expect("spawning the audio thread cannot fail");
Controller { tx, shared }
Controller {
tx,
shared,
playback_allowed,
generation,
start_paused,
}
}
/// Controller state the audio thread reads.
struct Generations {
current: Arc<AtomicU64>,
start_paused: Arc<AtomicBool>,
}
struct Output {
@@ -134,34 +270,103 @@ struct Output {
player: Player,
}
fn run(rx: Receiver<Command>, shared: Arc<Shared>, on_event: impl Fn(PlayerEvent)) {
/// Audio-thread state besides the output device.
struct Playing {
track_loaded: bool,
/// Position of the current source when it was appended: sources
/// positioned before playback (resumed podcast episodes) start there,
/// while rodio counts from zero until the next seek.
base: Duration,
/// Controller generation the current source was started under. When
/// the controller moved on, the end of this source is not reported: a
/// stop or another start is already on its way.
generation: u64,
}
fn run(
rx: Receiver<Command>,
shared: Arc<Shared>,
playback_allowed: Arc<AtomicBool>,
generations: Generations,
on_event: impl Fn(PlayerEvent),
) {
let generation = &generations.current;
let mut output: Option<Output> = None;
let mut track_loaded = false;
let mut playing = Playing {
track_loaded: false,
base: Duration::ZERO,
generation: generation.load(Ordering::SeqCst),
};
let mut last_len = 0usize;
loop {
match rx.recv_timeout(Duration::from_millis(100)) {
Ok(command) => {
if !playback_allowed.load(Ordering::Acquire)
&& matches!(
command,
Command::Play { .. }
| Command::PlaySource { .. }
| Command::Enqueue { .. }
| Command::Resume
)
{
continue;
}
if let Command::PlaySource {
generation: requested,
..
} = &command
&& *requested != generation.load(Ordering::SeqCst)
{
// Superseded while it was being prepared.
continue;
}
let started_under = match &command {
Command::PlaySource {
generation: requested,
..
} => Some(*requested),
Command::Play { .. } | Command::Stop => Some(generation.load(Ordering::SeqCst)),
_ => None,
};
// Commands change the source queue legitimately; resync the
// length so the next tick doesn't read it as a track ending.
handle(command, &mut output, &mut track_loaded, &on_event);
handle(
command,
&shared,
&generations.start_paused,
&mut output,
&mut playing,
&on_event,
);
if let Some(started_under) = started_under {
playing.generation = started_under;
}
last_len = output.as_ref().map_or(0, |out| out.player.len());
}
Err(RecvTimeoutError::Timeout) => {
if let Some(out) = &output {
let position = out.player.get_pos() + playing.base;
shared
.position_ms
.store(out.player.get_pos().as_millis() as u64, Ordering::Relaxed);
.store(position.as_millis() as u64, Ordering::Relaxed);
shared
.paused
.store(out.player.is_paused(), Ordering::Relaxed);
let len = out.player.len();
if track_loaded && len < last_len {
if playing.track_loaded && len < last_len {
// The next (gapless) source starts at zero.
playing.base = Duration::ZERO;
if len == 0 {
track_loaded = false;
playing.track_loaded = false;
}
for _ in len..last_len {
on_event(PlayerEvent::TrackFinished { has_next: len > 0 });
// A source that ended because it was superseded
// (its stream cancelled) did not finish.
if generation.load(Ordering::SeqCst) == playing.generation {
for _ in len..last_len {
on_event(PlayerEvent::TrackFinished { has_next: len > 0 });
}
}
}
last_len = len;
@@ -174,68 +379,59 @@ fn run(rx: Receiver<Command>, shared: Arc<Shared>, on_event: impl Fn(PlayerEvent
fn handle(
command: Command,
shared: &Arc<Shared>,
start_paused: &AtomicBool,
output: &mut Option<Output>,
track_loaded: &mut bool,
playing: &mut Playing,
on_event: &impl Fn(PlayerEvent),
) {
match command {
Command::Play {
reader,
byte_len,
mime_type,
seekable,
volume,
} => {
// The device is opened lazily on first playback so the app works
// on machines with no audio output until you actually press play.
if output.is_none() {
match DeviceSinkBuilder::open_default_sink() {
Ok(device) => {
let player = Player::connect_new(device.mixer());
*output = Some(Output {
_device: device,
player,
});
}
Err(err) => {
on_event(PlayerEvent::Failed(format!("no audio device: {err}")));
return;
}
}
}
let out = output.as_ref().expect("output opened above");
let mut builder = Decoder::builder()
.with_data(reader)
.with_seekable(true)
.with_gapless(true);
if let Some(len) = byte_len {
builder = builder.with_byte_len(len);
}
match builder.build() {
Ok(decoder) => {
out.player.stop();
out.player.set_volume(volume);
out.player.append(decoder);
out.player.play();
*track_loaded = true;
}
let Some(out) = ensure_output(output, on_event) else {
return;
};
match decode_source(reader, byte_len, mime_type.as_deref(), seekable) {
Ok(source) => start_source(out, source, volume, false, shared, on_event),
Err(err) => {
on_event(PlayerEvent::Failed(format!("cannot decode track: {err}")));
return;
}
}
playing.track_loaded = true;
playing.base = Duration::ZERO;
}
Command::PlaySource {
source,
volume,
start,
generation: _,
} => {
let Some(out) = ensure_output(output, on_event) else {
return;
};
let paused = start_paused.load(Ordering::SeqCst);
start_source(out, source, volume, paused, shared, on_event);
playing.track_loaded = true;
playing.base = start;
shared
.position_ms
.store(start.as_millis() as u64, Ordering::Relaxed);
}
Command::Enqueue { reader, byte_len } => {
let Some(out) = output.as_ref() else {
return;
};
let mut builder = Decoder::builder()
.with_data(reader)
.with_seekable(true)
.with_gapless(true);
if let Some(len) = byte_len {
builder = builder.with_byte_len(len);
}
match builder.build() {
Ok(decoder) => out.player.append(decoder),
match decode_source(reader, byte_len, None, true) {
Ok(source) => out.player.append(analyzer::AnalyzedSource::new(
source,
Arc::clone(&shared.analysis),
)),
Err(err) => {
on_event(PlayerEvent::Failed(format!(
"cannot decode next track: {err}"
@@ -243,15 +439,6 @@ fn handle(
}
}
}
Command::TogglePause => {
if let Some(out) = output {
if out.player.is_paused() {
out.player.play();
} else {
out.player.pause();
}
}
}
Command::Pause => {
if let Some(out) = output {
out.player.pause();
@@ -263,17 +450,29 @@ fn handle(
}
}
Command::Stop => {
if let Some(out) = output {
if let Some(out) = output.take() {
out.player.stop();
}
*track_loaded = false;
shared.analysis.clear();
playing.track_loaded = false;
playing.base = Duration::ZERO;
}
Command::Seek(position) => {
if let Some(out) = output {
if let Err(err) = out.player.try_seek(position) {
tracing::warn!(%err, "seek failed");
}
let result = match output {
Some(out) => out.player.try_seek(position).map_err(|err| err.to_string()),
None => Err("nothing is playing".to_string()),
};
match &result {
// rodio now reports absolute positions.
Ok(()) => playing.base = Duration::ZERO,
Err(err) => tracing::warn!(%err, "seek failed"),
}
shared.analysis.clear();
on_event(PlayerEvent::Seeked {
generation: playing.generation,
position,
result,
});
}
Command::SetVolume(volume) => {
if let Some(out) = output {
@@ -282,3 +481,157 @@ fn handle(
}
}
}
/// The device is opened lazily on first playback so the app works on
/// machines with no audio output until you actually press play.
fn ensure_output<'a>(
output: &'a mut Option<Output>,
on_event: &impl Fn(PlayerEvent),
) -> Option<&'a Output> {
if output.is_none() {
match DeviceSinkBuilder::open_default_sink() {
Ok(device) => {
let player = Player::connect_new(device.mixer());
*output = Some(Output {
_device: device,
player,
});
}
Err(err) => {
on_event(PlayerEvent::Failed(format!("no audio device: {err}")));
return None;
}
}
}
output.as_ref()
}
/// Replace whatever is playing with `source`.
fn start_source(
out: &Output,
source: DecodedSource,
volume: f32,
paused: bool,
shared: &Shared,
on_event: &impl Fn(PlayerEvent),
) {
shared.analysis.clear();
out.player.stop();
out.player.set_volume(volume);
out.player.append(analyzer::AnalyzedSource::new(
source,
Arc::clone(&shared.analysis),
));
if paused {
out.player.pause();
} else {
out.player.play();
}
on_event(PlayerEvent::Started);
}
pub(crate) type DecodedSource = Box<dyn Source + Send>;
pub(crate) fn decode_source(
reader: TrackReader,
byte_len: Option<u64>,
mime_type: Option<&str>,
seekable: bool,
) -> Result<DecodedSource, String> {
decode_source_with(reader, byte_len, mime_type, seekable, false)
}
/// `decode_source` with optional coarse (byte-estimate) seeking, which
/// remote streams need: an accurate MP3 seek decodes every frame before the
/// target, i.e. downloads it.
pub(crate) fn decode_source_with(
mut reader: TrackReader,
byte_len: Option<u64>,
mime_type: Option<&str>,
seekable: bool,
coarse_seek: bool,
) -> Result<DecodedSource, String> {
let mime_is_opus = mime_type.is_some_and(|mime| {
let mime = mime.to_ascii_lowercase();
mime == "audio/opus" || mime.contains("codecs=opus") || mime.contains("codecs=\"opus\"")
});
let ogg_is_opus = opus::is_ogg_opus(&mut reader)
.map_err(|error| format!("cannot inspect audio stream: {error}"))?;
if mime_is_opus || ogg_is_opus {
return opus::OggOpusSource::new(reader, byte_len, seekable)
.map(|source| Box::new(source) as DecodedSource);
}
let mut builder = Decoder::builder()
.with_data(reader)
.with_seekable(seekable)
.with_coarse_seek(coarse_seek)
.with_gapless(true);
if let Some(len) = byte_len {
builder = builder.with_byte_len(len);
}
if let Some(mime_type) = mime_type {
builder = builder.with_mime_type(mime_type);
}
builder
.build()
.map(|decoder| Box::new(decoder) as DecodedSource)
.map_err(|error| error.to_string())
}
#[cfg(test)]
mod tests {
use super::*;
/// A controller without the audio thread; the commands it sends are
/// returned instead (no audio device in tests).
fn detached() -> (Controller, Receiver<Command>) {
let (tx, rx) = std::sync::mpsc::channel();
let controller = Controller {
tx,
shared: Arc::default(),
playback_allowed: Arc::new(AtomicBool::new(true)),
generation: Arc::new(AtomicU64::new(0)),
start_paused: Arc::new(AtomicBool::new(false)),
};
(controller, rx)
}
/// The audio thread starts a prepared source with the intent read when
/// the source arrives (`Command::PlaySource` reads `start_paused`), so a
/// pause pressed while an episode was connecting is kept, and a resume
/// pressed after a paused start is too.
#[test]
fn play_and_pause_pressed_while_a_source_is_prepared_are_kept() {
let (controller, rx) = detached();
controller.stop();
let generation = controller.source_generation();
let superseded = controller.superseded_check(generation);
controller.expect_source(false);
controller.pause();
controller.play_source(
Box::new(rodio::source::Zero::new(
std::num::NonZero::new(1).unwrap(),
std::num::NonZero::new(8_000).unwrap(),
)),
1.0,
Duration::ZERO,
generation,
);
let commands: Vec<_> = rx.try_iter().collect();
assert!(matches!(
commands.as_slice(),
[Command::Stop, Command::Pause, Command::PlaySource { .. }]
));
assert!(controller.start_paused.load(Ordering::SeqCst));
assert!(!superseded(), "pausing does not supersede the source");
controller.expect_source(true);
controller.resume();
assert!(!controller.start_paused.load(Ordering::SeqCst));
// Another start or a stop supersedes the prepared source.
controller.stop();
assert!(superseded());
}
}
+433
View File
@@ -0,0 +1,433 @@
//! Ogg/Opus decoding for rodio.
//!
//! Rodio 0.22 can demux Ogg and decode Vorbis, but its Symphonia version does
//! not include an Opus decoder. This source keeps Symphonia's mature Ogg
//! demuxing and feeds the packets into the pure-Rust `rusty-opus` decoder.
use std::io::{self, Read, Seek, SeekFrom};
use std::sync::Arc;
use std::time::Duration;
use rodio::source::SeekError;
use rodio::{ChannelCount, SampleRate, Source};
use rusty_opus::OpusDecoder;
use symphonia::core::codecs::{CODEC_TYPE_OPUS, CodecParameters};
use symphonia::core::errors::Error as SymphoniaError;
use symphonia::core::formats::{FormatOptions, FormatReader, SeekMode, SeekTo};
use symphonia::core::io::{MediaSource, MediaSourceStream};
use symphonia::core::meta::MetadataOptions;
use symphonia::core::probe::Hint;
use super::TrackReader;
const OPUS_SAMPLE_RATE: u32 = 48_000;
const OPUS_SEEK_PREROLL_FRAMES: u64 = OPUS_SAMPLE_RATE as u64 * 80 / 1_000;
const SNIFF_BYTES: usize = 512;
/// Inspect the Ogg identification page without changing the reader position.
pub(super) fn is_ogg_opus(reader: &mut TrackReader) -> io::Result<bool> {
let position = reader.stream_position()?;
let mut header = [0; SNIFF_BYTES];
let read_result = reader.read(&mut header);
let rewind_result = reader.seek(SeekFrom::Start(position));
let read = read_result?;
rewind_result?;
Ok(header[..read].starts_with(b"OggS")
&& header[..read]
.windows(b"OpusHead".len())
.any(|window| window == b"OpusHead"))
}
struct ReaderMediaSource {
reader: TrackReader,
byte_len: Option<u64>,
seekable: bool,
}
impl Read for ReaderMediaSource {
fn read(&mut self, buffer: &mut [u8]) -> io::Result<usize> {
self.reader.read(buffer)
}
}
impl Seek for ReaderMediaSource {
fn seek(&mut self, position: SeekFrom) -> io::Result<u64> {
self.reader.seek(position)
}
}
impl MediaSource for ReaderMediaSource {
fn is_seekable(&self) -> bool {
self.seekable
}
fn byte_len(&self) -> Option<u64> {
self.byte_len
}
}
pub(super) struct OggOpusSource {
format: Box<dyn FormatReader>,
decoder: OpusDecoder,
track_id: u32,
channels: u16,
pre_skip: u64,
playable_frames: Option<u64>,
output_position_frames: u64,
discard_frames: u64,
output_gain: f32,
buffer: Vec<f32>,
scratch: Vec<f32>,
buffer_position: usize,
seekable: bool,
done: bool,
}
impl OggOpusSource {
pub(super) fn new(
reader: TrackReader,
byte_len: Option<u64>,
seekable: bool,
) -> Result<Self, String> {
let source = ReaderMediaSource {
reader,
byte_len,
seekable,
};
let stream = MediaSourceStream::new(Box::new(source), Default::default());
let mut hint = Hint::new();
hint.with_extension("ogg");
hint.mime_type("audio/ogg");
let format_options = FormatOptions {
enable_gapless: false,
..Default::default()
};
let probed = symphonia::default::get_probe()
.format(&hint, stream, &format_options, &MetadataOptions::default())
.map_err(|error| format!("cannot read Ogg container: {error}"))?;
let format = probed.format;
let (track_id, channels, pre_skip, playable_frames, output_gain) = {
let track = format
.default_track()
.ok_or_else(|| "Ogg container has no audio track".to_string())?;
if track.codec_params.codec != CODEC_TYPE_OPUS {
return Err("Ogg track is not Opus".to_string());
}
let channels = track
.codec_params
.channels
.map(|channels| channels.count() as u16)
.ok_or_else(|| "Opus track has no channel layout".to_string())?;
if !(1..=2).contains(&channels) {
return Err(format!(
"Opus track has {channels} channels; only mono and stereo are supported"
));
}
let extra_data = track.codec_params.extra_data.as_deref();
let pre_skip = opus_pre_skip(extra_data);
let playable_frames = opus_playable_frames(&track.codec_params, pre_skip);
let output_gain = opus_output_gain(extra_data);
(track.id, channels, pre_skip, playable_frames, output_gain)
};
let decoder = OpusDecoder::new(OPUS_SAMPLE_RATE as i32, usize::from(channels))
.map_err(|error| format!("cannot initialize Opus decoder: {error}"))?;
let mut source = Self {
format,
decoder,
track_id,
channels,
pre_skip,
playable_frames,
output_position_frames: 0,
discard_frames: pre_skip,
output_gain,
buffer: Vec::new(),
scratch: Vec::new(),
buffer_position: 0,
seekable,
done: false,
};
source.fill_buffer();
if source.buffer.is_empty() {
return Err("Opus track contains no decodable audio".to_string());
}
Ok(source)
}
fn fill_buffer(&mut self) {
self.buffer.clear();
self.buffer_position = 0;
while self.buffer.is_empty() && !self.done {
let packet = match self.format.next_packet() {
Ok(packet) => packet,
Err(SymphoniaError::IoError(error))
if error.kind() == io::ErrorKind::UnexpectedEof =>
{
self.done = true;
break;
}
Err(error) => {
tracing::warn!(%error, "Ogg/Opus demux failed");
self.done = true;
break;
}
};
if packet.track_id() != self.track_id {
continue;
}
let Ok(decoded_frames) = usize::try_from(packet.dur) else {
tracing::warn!("Ogg/Opus packet duration is too large");
self.done = true;
break;
};
if decoded_frames == 0 {
continue;
}
let sample_count = match decoded_frames.checked_mul(usize::from(self.channels)) {
Some(sample_count) => sample_count,
None => {
tracing::warn!("Ogg/Opus packet sample count overflow");
self.done = true;
break;
}
};
self.scratch.resize(sample_count, 0.0);
let frames = match self
.decoder
.decode(&packet.data, decoded_frames, &mut self.scratch)
{
Ok(frames) => frames,
Err(error) => {
tracing::warn!(%error, "Opus packet decode failed");
continue;
}
};
let discarded = self.discard_frames.min(frames as u64) as usize;
self.discard_frames -= discarded as u64;
let start_frame = discarded;
let remaining = self
.playable_frames
.map(|total| total.saturating_sub(self.output_position_frames))
.unwrap_or(u64::MAX);
let end_frame = frames
.min(start_frame.saturating_add(usize::try_from(remaining).unwrap_or(usize::MAX)));
if start_frame >= end_frame {
if self
.playable_frames
.is_some_and(|total| self.output_position_frames >= total)
{
self.done = true;
}
continue;
}
let channels = usize::from(self.channels);
let start = start_frame * channels;
let end = end_frame.saturating_mul(channels).min(self.scratch.len());
self.output_position_frames = self
.output_position_frames
.saturating_add((end_frame - start_frame) as u64);
self.buffer.extend(
self.scratch[start..end]
.iter()
.map(|sample| (sample * self.output_gain).clamp(-1.0, 1.0)),
);
if self
.playable_frames
.is_some_and(|total| self.output_position_frames >= total)
{
self.done = true;
}
}
}
fn reset_decoder(&mut self) -> Result<(), SeekError> {
self.decoder = OpusDecoder::new(OPUS_SAMPLE_RATE as i32, usize::from(self.channels))
.map_err(|error| seek_error(format!("cannot reset Opus decoder: {error}")))?;
Ok(())
}
}
impl Iterator for OggOpusSource {
type Item = f32;
fn next(&mut self) -> Option<Self::Item> {
loop {
if self.buffer_position < self.buffer.len() {
let sample = self.buffer[self.buffer_position];
self.buffer_position += 1;
return Some(sample);
}
if self.done {
return None;
}
self.fill_buffer();
}
}
fn size_hint(&self) -> (usize, Option<usize>) {
(self.buffer.len().saturating_sub(self.buffer_position), None)
}
}
impl Source for OggOpusSource {
fn current_span_len(&self) -> Option<usize> {
Some(self.buffer.len())
}
fn channels(&self) -> ChannelCount {
ChannelCount::new(self.channels).expect("Opus channel count was validated")
}
fn sample_rate(&self) -> SampleRate {
SampleRate::new(OPUS_SAMPLE_RATE).expect("Opus sample rate is non-zero")
}
fn total_duration(&self) -> Option<Duration> {
self.playable_frames
.map(|frames| Duration::from_secs_f64(frames as f64 / f64::from(OPUS_SAMPLE_RATE)))
}
fn try_seek(&mut self, position: Duration) -> Result<(), SeekError> {
if !self.seekable {
return Err(SeekError::NotSupported {
underlying_source: std::any::type_name::<Self>(),
});
}
let requested = duration_frames(position);
let target = self
.playable_frames
.map_or(requested, |total| requested.min(total));
let raw_target = target.saturating_add(self.pre_skip);
let preroll = raw_target.saturating_sub(OPUS_SEEK_PREROLL_FRAMES);
let seeked = self
.format
.seek(
SeekMode::Accurate,
SeekTo::TimeStamp {
ts: preroll,
track_id: self.track_id,
},
)
.map_err(|error| seek_error(format!("Ogg seek failed: {error}")))?;
self.reset_decoder()?;
self.buffer.clear();
self.buffer_position = 0;
self.output_position_frames = target;
self.discard_frames = raw_target.saturating_sub(seeked.actual_ts);
self.done = false;
self.fill_buffer();
Ok(())
}
}
fn duration_frames(duration: Duration) -> u64 {
let frames = duration.as_secs_f64() * f64::from(OPUS_SAMPLE_RATE);
frames.round().clamp(0.0, u64::MAX as f64) as u64
}
fn opus_pre_skip(extra_data: Option<&[u8]>) -> u64 {
extra_data
.filter(|header| header.len() >= 12)
.map(|header| u64::from(u16::from_le_bytes([header[10], header[11]])))
.unwrap_or(0)
}
fn opus_playable_frames(params: &CodecParameters, pre_skip: u64) -> Option<u64> {
let encoded_frames = params.n_frames?;
let padding = u64::from(params.padding.unwrap_or(0));
// Symphonia normally leaves the OpusHead pre-skip in `delay`. For a very
// short stream whose first audio page is also its last page, it instead
// reports the page's trailing padding there. Preserve that information so
// both one-page and ordinary Ogg/Opus streams end on the correct sample.
let one_page_padding = params
.delay
.map(u64::from)
.filter(|delay| *delay != pre_skip)
.unwrap_or(0);
Some(
encoded_frames
.saturating_sub(pre_skip)
.saturating_sub(padding)
.saturating_sub(one_page_padding),
)
}
fn opus_output_gain(extra_data: Option<&[u8]>) -> f32 {
let Some(header) = extra_data.filter(|header| header.len() >= 18) else {
return 1.0;
};
let gain_q8 = i16::from_le_bytes([header[16], header[17]]);
10.0_f32.powf(f32::from(gain_q8) / (20.0 * 256.0))
}
fn seek_error(message: String) -> SeekError {
SeekError::Other(Arc::new(io::Error::other(message)))
}
#[cfg(test)]
mod tests {
use std::io::Cursor;
use base64::Engine as _;
use super::*;
// 30 ms mono Ogg/Opus sine, encoded by FFmpeg/libopus. Keeping a real
// interoperable stream here catches container and codec regressions.
const OGG_OPUS: &str = "T2dnUwACAAAAAAAAAABkiBtVAAAAAFZb1toBE09wdXNIZWFkAQE4AYC7AAAAAABPZ2dTAAAAAAAAAAAAAGSIG1UBAAAAq+b2jQE+T3B1c1RhZ3MNAAAATGF2ZjYyLjEyLjEwMgEAAAAdAAAAZW5jb2Rlcj1MYXZjNjIuMjguMTAyIGxpYm9wdXNPZ2dTAATYBgAAAAAAAGSIG1UCAAAAEkNnrgT/NP8x+HJJRycQ5MhbeCeLhvfY79vodePsNuYR8hAn2iaItTjKzvL0UULTvai7BFd4FJ2BZdtZQn4K2vCS9rjadnLmp+u4QMCAJiL3MXbVJBVHjtDhATQq5rg5ZlscpBXWk/NqnQE/QaT/nhMi/VqnLKwRCFcpFnH/NqPx7RhjpvzicAu/blC/sRygALOf6blR6HYkOb7BLn/Vn3ijqdTVwCzwtcpWU2hbCXUOWnTEuXUOWaOmQKy8zmqYgzM7aOueo/2siHPpomLeiHPp4NH0cpD63qkSv4/XxX8HWdBtg9IvLpQ42ch0PrqI7BR4ZhvJoDmg45q/177KfOUxlfoG/8GpJWKTCpaN1u64it+1vkpE7sfaLIuSVNbz6BDOIREzM5pPkdIyBzqThkbRkGJr8KDGTyQyJfi0JXhIR5fGM2RptXd5mTRUZHmCz9dCMyKay/nzCir7oSDyEbWNlfaV7qzrxPXTNJRpJ/6GgfI3Ht2Y9jKPV8WkGzGO/Pyz+hznJTgJdGOpxRmzAWXmcwcSdI0TjPVLIs8SIBtipLhr0R+yDe2ar7ZQR3hxQzoIn5ydLO7mk8QZvr+4gAAAAAAAAAAAAAAAAAAAAAAAAE+e11+HmY5uncnz1m153WYm1urhAnMTa3qa3G/MIezSH+urKDn4eZAnEgz8PMnPgAOL22PlLS7647fYrYbJfnfYvLgwLpXSlHeh7VHf+GQd99vAzM/086lHsksCvwXkd12GFX2BTQbtW/3wPMmi4zL6VsKJUH/Q5ZQ00cvMtFDgSw5CLIg8nHONgH2/XVeZC+VwngKBeuzHHK4=";
fn fixture() -> Vec<u8> {
base64::engine::general_purpose::STANDARD
.decode(OGG_OPUS)
.unwrap()
}
#[test]
fn detects_and_decodes_ogg_opus() {
let bytes = fixture();
let len = bytes.len() as u64;
let mut reader: TrackReader = Box::new(Cursor::new(bytes));
assert!(is_ogg_opus(&mut reader).unwrap());
let source = OggOpusSource::new(reader, Some(len), true).unwrap();
assert_eq!(source.channels().get(), 1);
assert_eq!(source.sample_rate().get(), OPUS_SAMPLE_RATE);
let samples: Vec<_> = source.collect();
assert_eq!(samples.len(), 1_440);
assert!(samples.iter().any(|sample| sample.abs() > 0.001));
}
#[test]
fn seeks_within_ogg_opus() {
let bytes = fixture();
let len = bytes.len() as u64;
let reader: TrackReader = Box::new(Cursor::new(bytes));
let mut source = OggOpusSource::new(reader, Some(len), true).unwrap();
assert_eq!(source.by_ref().count(), 1_440);
source.try_seek(Duration::from_millis(15)).unwrap();
let samples: Vec<_> = source.collect();
assert_eq!(samples.len(), 720);
assert!(samples.iter().any(|sample| sample.abs() > 0.001));
}
#[test]
fn ogg_vorbis_header_is_not_misclassified_as_opus() {
let mut bytes =
b"OggS\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\x01\x1e\x01vorbis".to_vec();
bytes.resize(SNIFF_BYTES, 0);
let mut reader: TrackReader = Box::new(Cursor::new(bytes));
assert!(!is_ogg_opus(&mut reader).unwrap());
}
}
+257
View File
@@ -0,0 +1,257 @@
//! Public podcast cards found by federated search: their order next to the
//! music results, whether this device is already subscribed, an episode
//! preview read from the feed itself, and subscribing from a card.
//!
//! A card is a publisher's claim. Only its origin feed URL
//! ([`PodcastSearchHit::feed_url`]) is bound to the podcast id, so it is the
//! only URL this module ever fetches or subscribes with; the claimed moved
//! URLs are shown, never used. Nothing from the card is stored: subscribing
//! reads the feed from the podcast's own host like any other subscription,
//! and the new subscription is private.
use anyhow::{Result, bail};
use furumi_library::podcasts::PodcastStore;
use music_dht::LibraryItem;
use music_dht::podcast::{FeedUrl, PodcastId};
use music_dht::podcast_dht::{
FederatedSearchHit, PodcastDht, PodcastSearchHit, merge_search_results,
};
use super::fetch::{FeedBody, Fetcher, Validators};
use super::refresh::{self, Services, SubscribeReport};
/// Podcast hits asked from the discovery overlay per search.
pub const PODCAST_SEARCH_LIMIT: usize = 20;
/// Upper bound of one podcast search, the overlay's bootstrap included (the
/// overlay bounds only its lookups). The music lookup deadline.
pub const PODCAST_SEARCH_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(15);
/// Episodes kept in a preview (newest first).
pub const PREVIEW_EPISODES: usize = 200;
/// One public podcast in the search results.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PodcastHit {
pub hit: PodcastSearchHit,
/// The id this device gives the hit's origin URL
/// (`PodcastStore::resolve_podcast_id`): the card's id, unless the URL
/// is a known alias of a podcast this device already has.
pub local_id: PodcastId,
}
impl PodcastHit {
/// A hit not yet resolved against the local store.
pub fn new(hit: PodcastSearchHit) -> Self {
let local_id = hit.podcast_id.clone();
Self { hit, local_id }
}
/// Ids under which this device may know the podcast.
pub fn ids(&self) -> [&PodcastId; 2] {
[&self.local_id, &self.hit.podcast_id]
}
pub fn title(&self) -> &str {
&self.hit.card.title
}
}
/// The podcast hits of a federated search, in the order of
/// [`merge_search_results`] (exact title matches first). The TUI keeps its
/// own sections for the music results and searches podcasts separately;
/// the order of the podcast entries does not depend on the music items
/// (the merge is a stable exact-title partition), so [`search`] passes none.
pub fn podcast_hits(
query: &str,
music: Vec<LibraryItem>,
podcasts: Vec<PodcastSearchHit>,
) -> Vec<PodcastHit> {
merge_search_results(query, music, podcasts)
.into_iter()
.filter_map(|hit| match hit {
FederatedSearchHit::Podcast(hit) => Some(PodcastHit::new(hit)),
FederatedSearchHit::Music(_) => None,
})
.collect()
}
/// Searches the discovery overlay for public podcast cards, independently
/// of the music search. Bounded by `timeout` (the overlay bootstraps first
/// when it knows no peers, which its own lookup deadline does not cover).
/// No overlay, an error or a timeout give no hits; the warning names
/// neither the query nor any URL.
pub async fn search(
dht: Option<&PodcastDht>,
query: &str,
timeout: std::time::Duration,
) -> Vec<PodcastHit> {
let Some(dht) = dht else {
return Vec::new();
};
match tokio::time::timeout(timeout, dht.search(query, PODCAST_SEARCH_LIMIT)).await {
Ok(Ok(hits)) => podcast_hits(query, Vec::new(), hits),
Ok(Err(err)) => {
tracing::warn!("podcast discovery search failed: {err}");
Vec::new()
}
Err(_) => {
tracing::warn!(
timeout_s = timeout.as_secs(),
"podcast discovery search timed out"
);
Vec::new()
}
}
}
/// Resolves each hit's origin URL against the local store (feed aliases
/// included). Blocking.
pub fn resolve_local_ids(store: &PodcastStore, hits: &mut [PodcastHit]) -> Result<()> {
for hit in hits {
hit.local_id = store.resolve_podcast_id(&hit.hit.feed_url)?;
}
Ok(())
}
/// Subscribes to the podcast of a public card with its origin URL, never a
/// claimed one. The feed is read from its own host (following its own
/// redirects and `itunes:new-feed-url`), the subscription is private and
/// none of the card's metadata is stored.
pub async fn subscribe_from_hit(
services: &Services,
hit: &PodcastSearchHit,
now_ms: i64,
) -> Result<SubscribeReport> {
if PodcastId::from_feed_url(&hit.feed_url) != hit.podcast_id {
bail!("the card's feed URL does not match its podcast id");
}
refresh::subscribe_url(services, hit.feed_url.clone(), now_ms).await
}
/// One episode of a preview.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PreviewEpisode {
pub title: String,
pub season: Option<u32>,
pub episode_number: Option<u32>,
pub published_at_ms: Option<i64>,
pub duration_ms: Option<i64>,
}
/// What a podcast's own feed says, read without subscribing.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FeedPreview {
/// Channel title in the feed (may differ from the card's claim).
pub title: String,
pub episode_count: usize,
/// Season number (`None`: episodes without one) and episode count,
/// seasons in ascending order, unnumbered last.
pub seasons: Vec<(Option<u32>, usize)>,
/// Newest first, at most [`PREVIEW_EPISODES`].
pub episodes: Vec<PreviewEpisode>,
/// The feed answered from, or announced, another address.
pub moved_to: Option<FeedUrl>,
/// This device is subscribed to the podcast under `moved_to` (it
/// followed the feed's newer address, the card names the older one):
/// the card shows «Уже подписан». Set by [`preview_for`].
pub subscribed_as: Option<PodcastId>,
}
/// Reads the feed at `url` (a card's origin URL) for a preview. Nothing is
/// stored and no fetch state is recorded.
pub async fn preview(fetcher: &Fetcher, url: &FeedUrl) -> Result<FeedPreview> {
let response = fetcher.fetch_feed(url, Validators::default()).await?;
let FeedBody::Modified { body, .. } = response.body else {
bail!("the server answered 304 Not Modified to an unconditional request");
};
let feed = refresh::parse(body, &response.final_url).await?;
let announced = feed
.new_feed_url
.as_deref()
.and_then(|url| FeedUrl::parse(url).ok());
let moved_to = response
.moved_permanently_to
.or(announced)
.filter(|moved| moved != url);
let mut seasons: std::collections::BTreeMap<(bool, u32), usize> = Default::default();
for episode in &feed.episodes {
let key = match episode.season {
Some(season) => (false, season),
None => (true, 0),
};
*seasons.entry(key).or_default() += 1;
}
let mut episodes: Vec<PreviewEpisode> = feed
.episodes
.iter()
.map(|episode| PreviewEpisode {
title: episode.title.clone(),
season: episode.season,
episode_number: episode.episode_number,
published_at_ms: episode.published_at_ms,
duration_ms: episode.duration_ms,
})
.collect();
episodes.sort_by_key(|episode| std::cmp::Reverse(episode.published_at_ms));
episodes.truncate(PREVIEW_EPISODES);
Ok(FeedPreview {
title: feed.title.clone(),
episode_count: feed.episodes.len(),
seasons: seasons
.into_iter()
.map(|((unnumbered, season), count)| ((!unnumbered).then_some(season), count))
.collect(),
episodes,
moved_to,
subscribed_as: None,
})
}
/// [`preview`], plus whether this device already follows the podcast under
/// the newer address the feed moved to (`subscribed_as`). The store is only
/// read.
pub async fn preview_for(services: &Services, url: &FeedUrl) -> Result<FeedPreview> {
let mut preview = preview(&services.fetcher, url).await?;
if let Some(moved) = preview.moved_to.clone() {
let store = std::sync::Arc::clone(&services.store);
preview.subscribed_as =
tokio::task::spawn_blocking(move || refresh::subscribed_podcast(&store, &moved))
.await??;
}
Ok(preview)
}
/// A search hit for `feed_url` as one publisher would announce it (tests of
/// the search UI and of subscribing from a card).
#[cfg(test)]
pub(crate) fn test_hit(feed_url: &str, title: &str) -> PodcastSearchHit {
let feed_url = FeedUrl::parse(feed_url).unwrap();
let podcast_id = PodcastId::from_feed_url(&feed_url);
let publisher = music_dht::SecretKey::from_bytes(&[7; 32]).public();
PodcastSearchHit {
podcast_id: podcast_id.clone(),
feed_url: feed_url.clone(),
card: music_dht::podcast_dht::PodcastCard {
version: 1,
network_id: music_dht::NetworkId::from_name("furumi-tui-discovery-test"),
publisher,
podcast_id,
feed_url,
id_feed_url: None,
title: title.to_string(),
author: Some("Ferris Crab".to_string()),
description: Some("Weekly news about Rust.".to_string()),
image_url: None,
link: None,
language: Some("en".to_string()),
categories: vec!["Technology".to_string()],
episode_count: Some(12),
latest_episode_at_ms: Some(1_718_445_600_000),
revision: 1,
issued_at_ms: 1,
expires_at_ms: 2,
},
publishers: vec![publisher],
claimed_feed_urls: Vec::new(),
}
}
+500
View File
@@ -0,0 +1,500 @@
//! Public podcast cards: their order in the search results, the "already
//! subscribed" mark, the feed preview, subscribing from a card, and an
//! end-to-end run over two loopback discovery nodes with a local feed
//! server (no internet, temp directories only).
use std::sync::Arc;
use std::time::Duration;
use furumi_library::podcasts::PodcastListFilter;
use music_dht::NetworkId;
use music_dht::podcast::{FeedUrl, PodcastId};
use music_dht::podcast_dht::{ClaimedFeedUrl, FederatedSearchHit, SearchHitKind};
use super::discovery::{
PODCAST_SEARCH_TIMEOUT, PodcastHit, podcast_hits, preview, preview_for, resolve_local_ids,
search, subscribe_from_hit, test_hit,
};
use super::publication::{Publication, check_share, reconcile, set_shared};
use super::publication_tests::{Node, wait_for};
use super::refresh::{refresh, subscribe};
use super::test_server::Route;
use super::tests::{NOW, fixture, rss};
#[test]
fn podcast_hits_put_exact_titles_first_and_keep_only_podcasts() {
let other = test_hit("https://feeds.example.test/weekly.xml", "Rust Radio Weekly");
let exact = test_hit("https://feeds.example.test/radio.xml", "Rust Radio");
let hits = podcast_hits("rust radio", Vec::new(), vec![other.clone(), exact.clone()]);
let ids: Vec<&PodcastId> = hits.iter().map(|hit| &hit.hit.podcast_id).collect();
assert_eq!(ids, [&exact.podcast_id, &other.podcast_id]);
// Unresolved hits use the card's id; the type marker is "podcast".
assert!(hits.iter().all(|hit| hit.local_id == hit.hit.podcast_id));
assert_eq!(hits[0].hit.kind(), SearchHitKind::Podcast);
assert_eq!(
FederatedSearchHit::Podcast(exact).kind().as_str(),
"podcast"
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn podcast_search_is_bounded_and_empty_without_the_overlay() {
// Federation off (no overlay): no hits, nothing to wait for.
assert!(
search(None, "rust radio", PODCAST_SEARCH_TIMEOUT)
.await
.is_empty()
);
// An overlay that knows no overlay peers bootstraps from its music-DHT
// contacts before it searches, outside its own lookup deadline. With a
// contact that no longer answers, the search still ends at the bound.
let temp = tempfile::tempdir().unwrap();
let network = NetworkId::from_name("furumi-tui-podcast-search-bound-test");
let a = Node::start(&temp.path().join("a"), network).await;
let gone = Node::start(&temp.path().join("gone"), network).await;
a.service
.connect(gone.service.ticket().await.unwrap())
.await
.unwrap();
wait_for("a music DHT contact", async || {
(!a.service.known_peers().is_empty()).then_some(())
})
.await;
gone.stop().await;
assert_eq!(a.dht.known_peers(), 0);
let bound = Duration::from_millis(500);
let started = std::time::Instant::now();
let hits = search(Some(&a.dht), "rust radio", bound).await;
let elapsed = started.elapsed();
assert!(hits.is_empty());
assert!(elapsed < bound + Duration::from_secs(1), "took {elapsed:?}");
a.stop().await;
}
#[tokio::test]
async fn subscribing_from_a_card_matches_subscribing_by_url() {
let by_url = fixture();
let from_card = fixture();
by_url.server.set(
"/feed.xml",
Route::new(
rss(&[("a", "Pilot"), ("b", "Second")]),
"application/rss+xml",
),
);
let url = by_url.server.url("/feed.xml");
let typed = subscribe(&by_url.services, &url, NOW).await.unwrap();
let hit = test_hit(&url, "A card title that is only a claim");
let report = subscribe_from_hit(&from_card.services, &hit, NOW)
.await
.unwrap();
assert_eq!(report.podcast_id, typed.podcast_id);
assert_eq!(report.podcast_id, hit.podcast_id);
assert_eq!(report.new_episodes, 2);
// Metadata comes from the feed, never from the card.
assert_eq!(report.title, "Test Show");
// A private subscription: no share decision was written.
assert_eq!(from_card.log.kinds(), ["podcast_subscription_set"]);
let store = &from_card.services.store;
assert_eq!(store.share(&report.podcast_id).unwrap(), None);
let rows = store.list_podcasts(PodcastListFilter::Subscribed).unwrap();
assert_eq!(rows.len(), 1);
assert!(!rows[0].shared);
assert_eq!(rows[0].meta.title, "Test Show");
// Subscribing again from the card changes nothing.
let again = subscribe_from_hit(&from_card.services, &hit, NOW + 1)
.await
.unwrap();
assert!(again.already_subscribed);
assert_eq!(from_card.log.kinds().len(), 1);
}
#[tokio::test]
async fn subscribing_from_a_card_never_fetches_a_claimed_url() {
let f = fixture();
// The origin URL moved permanently; a publisher also claims a URL of its
// own choosing.
f.server.set(
"/origin.xml",
Route::redirect(301, &f.server.url("/moved.xml")),
);
f.server.set(
"/moved.xml",
Route::new(rss(&[("a", "Pilot")]), "application/rss+xml"),
);
f.server.set(
"/claimed.xml",
Route::new(rss(&[("x", "Imposter")]), "application/rss+xml"),
);
let origin = FeedUrl::parse(&f.server.url("/origin.xml")).unwrap();
let moved = FeedUrl::parse(&f.server.url("/moved.xml")).unwrap();
let claimed = FeedUrl::parse(&f.server.url("/claimed.xml")).unwrap();
let mut hit = test_hit(origin.as_str(), "Rust Radio");
hit.claimed_feed_urls = vec![ClaimedFeedUrl {
feed_url: claimed.clone(),
publishers: hit.publishers.clone(),
}];
hit.card.feed_url = claimed.clone();
hit.card.id_feed_url = Some(origin.clone());
let report = subscribe_from_hit(&f.services, &hit, NOW).await.unwrap();
assert_eq!(report.podcast_id, PodcastId::from_feed_url(&origin));
assert!(f.server.requests("/claimed.xml").is_empty());
let aliases = f.services.store.feed_aliases(&report.podcast_id).unwrap();
assert!(
aliases.contains(&moved),
"the feed's own redirect is an alias"
);
assert!(
!aliases.contains(&claimed),
"a claim never becomes an alias"
);
// A card whose id is not the hash of its origin URL is refused before
// anything is fetched or stored.
let other = fixture();
let mut forged = test_hit(&f.server.url("/moved.xml"), "Rust Radio");
forged.podcast_id = hit.podcast_id.clone();
let requests = f.server.requests("/moved.xml").len();
assert!(
subscribe_from_hit(&other.services, &forged, NOW)
.await
.is_err()
);
assert_eq!(f.server.requests("/moved.xml").len(), requests);
assert!(other.log.kinds().is_empty());
}
#[tokio::test]
async fn hits_resolve_to_the_podcast_a_feed_alias_belongs_to() {
let f = fixture();
f.server
.set("/old.xml", Route::redirect(301, &f.server.url("/new.xml")));
f.server.set(
"/new.xml",
Route::new(rss(&[("a", "Pilot")]), "application/rss+xml"),
);
let subscribed = subscribe(&f.services, &f.server.url("/old.xml"), NOW)
.await
.unwrap();
// Somebody else subscribed with the new address and shares that card.
let mut hits = vec![
PodcastHit::new(test_hit(&f.server.url("/new.xml"), "Test Show")),
PodcastHit::new(test_hit(
"https://feeds.example.test/unknown.xml",
"Unknown",
)),
];
assert_ne!(hits[0].hit.podcast_id, subscribed.podcast_id);
resolve_local_ids(&f.services.store, &mut hits).unwrap();
assert_eq!(hits[0].local_id, subscribed.podcast_id);
assert!(hits[0].ids().contains(&&subscribed.podcast_id));
assert_eq!(hits[1].local_id, hits[1].hit.podcast_id);
}
#[tokio::test]
async fn a_card_for_an_older_address_finds_the_subscription_under_the_newer_one() {
use furumi_library::podcasts::PodcastListFilter;
// The user follows the feed under its newer address; a long-standing
// publisher's card names the older one (the card's origin).
let f = fixture();
let feed = |announce: Option<&str>| {
let announce = announce
.map(|url| format!("<itunes:new-feed-url>{url}</itunes:new-feed-url>"))
.unwrap_or_default();
format!(
"<?xml version=\"1.0\"?><rss version=\"2.0\" \
xmlns:itunes=\"http://www.itunes.com/dtds/podcast-1.0.dtd\"><channel>\
<title>Test Show</title>{announce}{}</channel></rss>",
item("a", "Pilot", 1, "Sat, 01 Jun 2024 10:00:00 GMT"),
)
};
let subscribed_rows = || {
f.services
.store
.list_podcasts(PodcastListFilter::Subscribed)
.unwrap()
.len()
};
// 1. The old address redirects permanently to the new one.
f.server
.set("/old.xml", Route::redirect(301, &f.server.url("/new.xml")));
f.server
.set("/new.xml", Route::new(feed(None), "application/rss+xml"));
let followed = subscribe(&f.services, &f.server.url("/new.xml"), NOW)
.await
.unwrap();
let card = test_hit(&f.server.url("/old.xml"), "Test Show");
let url = card.feed_url.clone();
let preview = preview_for(&f.services, &url).await.unwrap();
assert_eq!(preview.subscribed_as.as_ref(), Some(&followed.podcast_id));
let report = subscribe_from_hit(&f.services, &card, NOW).await.unwrap();
assert!(report.already_subscribed);
assert_eq!(report.podcast_id, followed.podcast_id);
assert_eq!(subscribed_rows(), 1);
// 2. The old address only announces the new one (itunes:new-feed-url,
// no redirect): no second subscription for the same podcast.
let new_url = f.server.url("/new2.xml");
f.server
.set("/new2.xml", Route::new(feed(None), "application/rss+xml"));
f.server.set(
"/old2.xml",
Route::new(feed(Some(&new_url)), "application/rss+xml"),
);
let followed = subscribe(&f.services, &new_url, NOW).await.unwrap();
let kinds = f.log.kinds().len();
let card = test_hit(&f.server.url("/old2.xml"), "Test Show");
let url = card.feed_url.clone();
let preview = preview_for(&f.services, &url).await.unwrap();
assert_eq!(preview.moved_to, Some(FeedUrl::parse(&new_url).unwrap()));
assert_eq!(preview.subscribed_as.as_ref(), Some(&followed.podcast_id));
let report = subscribe_from_hit(&f.services, &card, NOW).await.unwrap();
assert!(report.already_subscribed);
assert_eq!(report.podcast_id, followed.podcast_id);
assert_eq!(subscribed_rows(), 2, "one row per podcast");
assert_eq!(f.log.kinds().len(), kinds, "nothing was written");
// A card whose feed moved to an address this device does not follow
// is not marked.
f.server.set(
"/elsewhere.xml",
Route::new(
feed(Some("https://feeds.example.test/unknown.xml")),
"application/rss+xml",
),
);
let url = FeedUrl::parse(&f.server.url("/elsewhere.xml")).unwrap();
let preview = preview_for(&f.services, &url).await.unwrap();
assert!(preview.moved_to.is_some());
assert_eq!(preview.subscribed_as, None);
}
#[tokio::test]
async fn preview_reads_seasons_and_episodes_without_storing_anything() {
let f = fixture();
let new_url = "https://feeds.example.test/new-home.xml";
let feed = format!(
"<?xml version=\"1.0\"?><rss version=\"2.0\" \
xmlns:itunes=\"http://www.itunes.com/dtds/podcast-1.0.dtd\"><channel>\
<title>Feed Title</title><itunes:new-feed-url>{new_url}</itunes:new-feed-url>\
{}{}{}{}</channel></rss>",
item("a", "One", 1, "Sat, 01 Jun 2024 10:00:00 GMT"),
item("b", "Two", 1, "Sat, 08 Jun 2024 10:00:00 GMT"),
item("c", "Three", 2, "Sat, 15 Jun 2024 10:00:00 GMT"),
"<item><title>Bonus</title><guid>d</guid>\
<pubDate>Sat, 22 Jun 2024 10:00:00 GMT</pubDate>\
<enclosure url=\"/d.mp3\" type=\"audio/mpeg\"/></item>",
);
f.server
.set("/feed.xml", Route::new(feed, "application/rss+xml"));
let url = FeedUrl::parse(&f.server.url("/feed.xml")).unwrap();
let preview = preview(&f.services.fetcher, &url).await.unwrap();
assert_eq!(preview.title, "Feed Title");
assert_eq!(preview.episode_count, 4);
assert_eq!(preview.seasons, [(Some(1), 2), (Some(2), 1), (None, 1)]);
let titles: Vec<&str> = preview.episodes.iter().map(|e| e.title.as_str()).collect();
assert_eq!(titles, ["Bonus", "Three", "Two", "One"]);
assert_eq!(preview.episodes[1].season, Some(2));
assert_eq!(preview.episodes[1].duration_ms, Some(45 * 60 * 1000));
assert_eq!(
preview.moved_to,
Some(FeedUrl::parse(new_url).unwrap()),
"the feed announced a new address"
);
// Nothing was stored: no podcast, no fetch state, no operation.
let store = &f.services.store;
assert!(
store
.list_podcasts(PodcastListFilter::All)
.unwrap()
.is_empty()
);
assert!(f.log.kinds().is_empty());
}
fn item(guid: &str, title: &str, season: u32, date: &str) -> String {
format!(
"<item><title>{title}</title><guid>{guid}</guid><pubDate>{date}</pubDate>\
<itunes:season>{season}</itunes:season><itunes:duration>45:00</itunes:duration>\
<enclosure url=\"/{guid}.mp3\" type=\"audio/mpeg\"/></item>"
)
}
// ---------------------------------------------------------------------------
// Two loopback nodes and a local feed server
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn a_stranger_finds_a_shared_card_subscribes_and_refreshes_from_the_feed() {
tokio::time::timeout(Duration::from_secs(240), stranger_subscribes())
.await
.unwrap();
}
async fn stranger_subscribes() {
let temp = tempfile::tempdir().unwrap();
let network = NetworkId::from_name("furumi-tui-podcast-discovery-test");
// A shares a podcast. B is another user's TUI outside A's
// trusted-device group: no device sync between them, only the overlay.
let a = Node::start(&temp.path().join("a"), network).await;
let b = Node::start(&temp.path().join("b"), network).await;
b.service
.connect(a.service.ticket().await.unwrap())
.await
.unwrap();
wait_for("music DHT contacts", async || {
(!a.service.known_peers().is_empty() && !b.service.known_peers().is_empty()).then_some(())
})
.await;
for node in [&a, &b] {
node.dht.bootstrap().await.unwrap();
}
wait_for("overlay contacts", async || {
(a.dht.known_peers() >= 1 && b.dht.known_peers() >= 1).then_some(())
})
.await;
// The podcast's own host (a local HTTP server).
let user_a = fixture();
let user_b = fixture();
let feed = &user_a.server;
feed.set(
"/show.xml",
Route::new(
rss(&[("a", "Pilot"), ("b", "Second")]),
"application/rss+xml",
),
);
let feed_url = FeedUrl::parse(&feed.url("/show.xml")).unwrap();
let private_url = feed.url("/diary.xml");
feed.set(
"/diary.xml",
Route::new(rss(&[("p", "Private entry")]), "application/rss+xml"),
);
// A subscribes to two podcasts and shares one. The local address looks
// private, so A confirms exactly these URLs first (the dialog).
let shared = subscribe(&user_a.services, feed_url.as_str(), NOW)
.await
.unwrap();
let private = subscribe(&user_a.services, &private_url, NOW)
.await
.unwrap();
let store_a = Arc::clone(&user_a.services.store);
let confirmations = Arc::clone(&user_a.services.confirmations);
let check = check_share(&store_a, &confirmations, &shared.podcast_id).unwrap();
set_shared(
&store_a,
&confirmations,
&shared.podcast_id,
true,
check.needs_confirmation().then_some(check.urls),
|| {
user_a
.services
.log
.record(&mut |stamps| store_a.set_shared(stamps, &shared.podcast_id, true))
},
)
.unwrap();
let report = reconcile(
&a.dht,
Some(Arc::clone(&store_a)),
Arc::clone(&confirmations),
)
.await;
assert_eq!(report.error, None);
assert_eq!(
report.podcasts.get(&shared.podcast_id),
Some(&Publication::Published)
);
// B searches like the search view does: overlay search, merged order,
// resolved against B's own store.
let mut hits = wait_for("the shared card", async || {
let found = search(Some(&b.dht), "test show", PODCAST_SEARCH_TIMEOUT).await;
(!found.is_empty()).then_some(found)
})
.await;
assert_eq!(hits.len(), 1, "the private subscription is not found");
resolve_local_ids(&user_b.services.store, &mut hits).unwrap();
let hit = hits.remove(0);
assert_eq!(hit.hit.kind(), SearchHitKind::Podcast);
assert_eq!(hit.hit.podcast_id, shared.podcast_id);
assert_eq!(hit.hit.feed_url, feed_url);
assert_eq!(hit.hit.publishers, vec![a.service.endpoint_id()]);
assert_eq!(hit.local_id, shared.podcast_id);
assert!(
b.dht
.lookup_podcast(&private.podcast_id)
.await
.unwrap()
.is_none()
);
// "Подписаться": B reads the feed from its host, not from A.
let before = feed.requests("/show.xml").len();
let subscribed = subscribe_from_hit(&user_b.services, &hit.hit, NOW)
.await
.unwrap();
assert_eq!(subscribed.podcast_id, shared.podcast_id, "same podcast id");
assert_eq!(subscribed.new_episodes, 2);
assert_eq!(feed.requests("/show.xml").len(), before + 1);
let store_b = &user_b.services.store;
assert_eq!(store_b.share(&subscribed.podcast_id).unwrap(), None);
assert_eq!(user_b.log.kinds(), ["podcast_subscription_set"]);
assert!(
b.dht.published().await.unwrap().is_empty(),
"B publishes nothing"
);
// B refreshes on its own from the feed.
feed.set(
"/show.xml",
Route::new(
rss(&[("a", "Pilot"), ("b", "Second"), ("c", "Third")]),
"application/rss+xml",
),
);
let refreshed = refresh(&user_b.services, &subscribed.podcast_id, &feed_url, NOW + 1)
.await
.unwrap();
assert_eq!(refreshed.new_episodes, 1);
// A stops sharing: the card disappears for B, B's subscription stays.
user_a
.services
.log
.record(&mut |stamps| store_a.set_shared(stamps, &shared.podcast_id, false))
.unwrap();
let report = reconcile(&a.dht, Some(Arc::clone(&store_a)), confirmations).await;
assert_eq!(report.podcasts.get(&shared.podcast_id), None);
assert!(
b.dht
.lookup_podcast(&shared.podcast_id)
.await
.unwrap()
.is_none()
);
assert!(
search(Some(&b.dht), "test show", PODCAST_SEARCH_TIMEOUT)
.await
.is_empty()
);
let rows = store_b
.list_podcasts(PodcastListFilter::Subscribed)
.unwrap();
assert_eq!(rows.len(), 1);
assert_eq!(rows[0].podcast_id, shared.podcast_id);
assert!(!rows[0].shared);
let refreshed = refresh(&user_b.services, &subscribed.podcast_id, &feed_url, NOW + 2)
.await
.unwrap();
assert_eq!(refreshed.new_episodes, 0);
a.stop().await;
b.stop().await;
}
+389
View File
@@ -0,0 +1,389 @@
//! HTTP for podcast feeds and cover images.
//!
//! Redirects are followed by hand so the caller learns where the feed
//! really lives: the address reached by the leading permanent (301/308)
//! hops is where the feed moved, and the store records it as the new fetch
//! URL (the old one becomes an alias). Temporary hops after it (a CDN or a
//! tracking prefix) do not move the feed further. Conditional requests
//! (`If-None-Match` / `If-Modified-Since`), response size caps, timeouts and
//! the user agent are fixed here; parsing and storage happen elsewhere.
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::Duration;
use anyhow::{Context, Result, anyhow, bail};
use music_dht::podcast::{FeedUrl, PodcastId};
use reqwest::header::{
ACCEPT, ETAG, HeaderMap, IF_MODIFIED_SINCE, IF_NONE_MATCH, LAST_MODIFIED, LOCATION, RETRY_AFTER,
};
use reqwest::{StatusCode, Url};
/// Hard cap on a feed document (large catalogs are a few MiB).
pub const MAX_FEED_BYTES: usize = 32 * 1024 * 1024;
/// Hard cap on a cover image.
pub const MAX_COVER_BYTES: usize = 10 * 1024 * 1024;
/// Redirect hops followed before giving up.
pub const MAX_REDIRECTS: usize = 10;
/// TCP + TLS connection setup.
pub const CONNECT_TIMEOUT: Duration = Duration::from_secs(15);
/// Whole request, including the body, per hop.
pub const REQUEST_TIMEOUT: Duration = Duration::from_secs(60);
/// A whole feed or cover fetch, all redirect hops and the body included, so
/// a slow server holds one of the few refresh slots for at most this long.
#[cfg(not(test))]
pub const FETCH_DEADLINE: Duration = Duration::from_secs(120);
#[cfg(test)]
pub const FETCH_DEADLINE: Duration = Duration::from_secs(3);
/// Sent with every podcast request.
pub const USER_AGENT: &str = concat!("furumi/", env!("CARGO_PKG_VERSION"), " (podcast reader)");
const FEED_ACCEPT: &str = "application/rss+xml, application/atom+xml, application/xml;q=0.9, \
text/xml;q=0.9, */*;q=0.5";
/// HTTP validators of the last successful fetch.
#[derive(Debug, Clone, Copy, Default)]
pub struct Validators<'a> {
pub etag: Option<&'a str>,
pub last_modified: Option<&'a str>,
}
/// What a feed request returned.
#[derive(Debug)]
pub enum FeedBody {
/// `304 Not Modified` to a conditional request.
NotModified,
/// A new document with its validators.
Modified {
body: Vec<u8>,
etag: Option<String>,
last_modified: Option<String>,
},
}
/// A feed response and the redirect chain that led to it.
#[derive(Debug)]
pub struct FeedResponse {
pub body: FeedBody,
/// URL that finally answered, canonicalized; the base for relative
/// URLs in the document.
pub final_url: FeedUrl,
/// Where the leading permanent redirects (301/308, one or more, before
/// any temporary one) lead: the feed's new address. `None` when the
/// first hop was temporary or there was none. Temporary redirects
/// (tracking prefixes, CDNs) never move a feed.
pub moved_permanently_to: Option<FeedUrl>,
/// Redirect hops followed.
pub redirects: usize,
}
/// A non-success HTTP status, with the server's `Retry-After` (seconds form)
/// so the scheduler can back off as asked.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HttpStatusError {
pub status: u16,
pub retry_after: Option<Duration>,
}
impl std::fmt::Display for HttpStatusError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let reason = StatusCode::from_u16(self.status)
.ok()
.and_then(|status| status.canonical_reason())
.unwrap_or("error");
write!(f, "HTTP {} {reason}", self.status)
}
}
impl std::error::Error for HttpStatusError {}
/// Shared HTTP client for feeds and covers.
pub struct Fetcher {
client: reqwest::Client,
covers_dir: PathBuf,
}
impl Fetcher {
pub fn new(covers_dir: PathBuf) -> Result<Fetcher> {
let _ = rustls::crypto::ring::default_provider().install_default();
let client = reqwest::Client::builder()
.connect_timeout(CONNECT_TIMEOUT)
.timeout(REQUEST_TIMEOUT)
.redirect(reqwest::redirect::Policy::none())
.user_agent(USER_AGENT)
.build()
.context("building the podcast HTTP client")?;
Ok(Fetcher { client, covers_dir })
}
/// GET of a feed. `validators` make it conditional; they are dropped
/// after a permanent redirect because they belong to the old URL.
pub async fn fetch_feed(
&self,
url: &FeedUrl,
validators: Validators<'_>,
) -> Result<FeedResponse> {
within_deadline("feed", self.fetch_feed_unbounded(url, validators)).await
}
async fn fetch_feed_unbounded(
&self,
url: &FeedUrl,
validators: Validators<'_>,
) -> Result<FeedResponse> {
let Followed {
response,
url: final_url,
moved_permanently_to,
redirects,
conditional,
} = self
.get_following(url.as_str(), Some(FEED_ACCEPT), validators)
.await?;
let final_url = FeedUrl::parse(final_url.as_str()).map_err(|err| {
anyhow!(
"the feed was redirected to an unsupported URL {}: {err}",
redact(&final_url)
)
})?;
// An address that is not a valid feed URL is not worth moving to.
let moved_permanently_to =
moved_permanently_to.and_then(|url| FeedUrl::parse(url.as_str()).ok());
let status = response.status();
if status == StatusCode::NOT_MODIFIED {
if !conditional {
bail!("the server answered 304 Not Modified to an unconditional request");
}
return Ok(FeedResponse {
body: FeedBody::NotModified,
final_url,
moved_permanently_to,
redirects,
});
}
if !status.is_success() {
return Err(status_error(status, response.headers()).into());
}
let etag = header_string(response.headers(), ETAG);
let last_modified = header_string(response.headers(), LAST_MODIFIED);
let body = read_capped(response, MAX_FEED_BYTES, "feed").await?;
Ok(FeedResponse {
body: FeedBody::Modified {
body,
etag,
last_modified,
},
final_url,
moved_permanently_to,
redirects,
})
}
/// Downloads a cover image into the covers directory; returns its path.
pub async fn fetch_cover(&self, podcast_id: &PodcastId, image_url: &str) -> Result<PathBuf> {
let body = within_deadline("cover image", self.download_cover(image_url)).await?;
let format = image::guess_format(&body).context("the cover is not a supported image")?;
let extension = format.extensions_str().first().copied().unwrap_or("img");
let name = cover_file_name(podcast_id, image_url, extension);
let dir = self.covers_dir.clone();
tokio::task::spawn_blocking(move || write_atomically(&dir, &name, &body))
.await
.map_err(|err| anyhow!("cover writer task failed: {err}"))?
}
async fn download_cover(&self, image_url: &str) -> Result<Vec<u8>> {
let response = self
.get_following(image_url, None, Validators::default())
.await?
.response;
let status = response.status();
if !status.is_success() {
return Err(status_error(status, response.headers()).into());
}
read_capped(response, MAX_COVER_BYTES, "cover image").await
}
/// GET following up to [`MAX_REDIRECTS`] http(s) redirects by hand.
async fn get_following(
&self,
url: &str,
accept: Option<&str>,
validators: Validators<'_>,
) -> Result<Followed> {
let mut current = Url::parse(url).with_context(|| format!("invalid URL {url:?}"))?;
check_scheme(&current)?;
// Still in the leading run of permanent hops.
let mut permanent_run = true;
let mut moved_permanently_to = None;
let mut send_validators = true;
let mut hops = 0;
loop {
let mut request = self.client.get(current.clone());
if let Some(accept) = accept {
request = request.header(ACCEPT, accept);
}
if send_validators {
if let Some(etag) = validators.etag {
request = request.header(IF_NONE_MATCH, etag);
}
if let Some(last_modified) = validators.last_modified {
request = request.header(IF_MODIFIED_SINCE, last_modified);
}
}
let response = request
.send()
.await
// reqwest errors print the full URL, query tokens included.
.map_err(reqwest::Error::without_url)
.with_context(|| format!("requesting {}", redact(&current)))?;
let status = response.status();
if !status.is_redirection() || status == StatusCode::NOT_MODIFIED {
let conditional = send_validators
&& (validators.etag.is_some() || validators.last_modified.is_some());
return Ok(Followed {
response,
url: current,
moved_permanently_to,
redirects: hops,
conditional,
});
}
let location = response
.headers()
.get(LOCATION)
.and_then(|value| value.to_str().ok())
.ok_or_else(|| anyhow!("HTTP {status} redirect without a Location header"))?;
let next = current
.join(location.trim())
.with_context(|| format!("invalid redirect location {location:?}"))?;
check_scheme(&next)?;
hops += 1;
if hops > MAX_REDIRECTS {
bail!("too many redirects (more than {MAX_REDIRECTS})");
}
let permanent = matches!(
status,
StatusCode::MOVED_PERMANENTLY | StatusCode::PERMANENT_REDIRECT
);
permanent_run &= permanent;
if permanent_run {
moved_permanently_to = Some(next.clone());
}
if permanent {
send_validators = false;
}
current = next;
}
}
}
/// Fails `fetch` once [`FETCH_DEADLINE`] has passed.
async fn within_deadline<T>(what: &str, fetch: impl Future<Output = Result<T>>) -> Result<T> {
tokio::time::timeout(FETCH_DEADLINE, fetch)
.await
.unwrap_or_else(|_| {
bail!(
"the {what} took longer than {} seconds",
FETCH_DEADLINE.as_secs()
)
})
}
struct Followed {
response: reqwest::Response,
/// URL that answered.
url: Url,
/// Target of the leading permanent hops.
moved_permanently_to: Option<Url>,
redirects: usize,
/// The final request carried validators.
conditional: bool,
}
fn check_scheme(url: &Url) -> Result<()> {
if !matches!(url.scheme(), "http" | "https") {
bail!("unsupported URL scheme {:?}", url.scheme());
}
if url.host_str().is_none_or(str::is_empty) {
bail!("URL has no host");
}
Ok(())
}
/// The URL without query and fragment, for messages and logs: feed URLs
/// may carry private tokens in their query.
pub fn redact(url: &Url) -> String {
let mut shown = url.clone();
if shown.query().is_some() {
shown.set_query(Some("…"));
}
shown.set_fragment(None);
shown.to_string()
}
fn header_string(headers: &HeaderMap, name: reqwest::header::HeaderName) -> Option<String> {
headers
.get(name)
.and_then(|value| value.to_str().ok())
.map(str::trim)
.filter(|value| !value.is_empty())
.map(str::to_string)
}
fn status_error(status: StatusCode, headers: &HeaderMap) -> HttpStatusError {
let retry_after = header_string(headers, RETRY_AFTER)
.and_then(|value| value.parse::<u64>().ok())
.map(Duration::from_secs);
HttpStatusError {
status: status.as_u16(),
retry_after,
}
}
async fn read_capped(mut response: reqwest::Response, cap: usize, what: &str) -> Result<Vec<u8>> {
if let Some(len) = response.content_length()
&& len > cap as u64
{
bail!("the {what} is too large ({len} bytes, limit {cap})");
}
let mut body = Vec::new();
while let Some(chunk) = response
.chunk()
.await
.map_err(reqwest::Error::without_url)
.with_context(|| format!("reading the {what}"))?
{
if body.len() + chunk.len() > cap {
bail!("the {what} is too large (over {cap} bytes)");
}
body.extend_from_slice(&chunk);
}
Ok(body)
}
/// Stable per podcast and image URL, so a changed image gets a new file and
/// the previous one can be removed.
fn cover_file_name(podcast_id: &PodcastId, image_url: &str, extension: &str) -> String {
let podcast = blake3::hash(podcast_id.as_str().as_bytes()).to_hex();
let image = blake3::hash(image_url.as_bytes()).to_hex();
format!("{}-{}.{extension}", &podcast[..16], &image[..16])
}
fn write_atomically(dir: &Path, name: &str, bytes: &[u8]) -> Result<PathBuf> {
static COUNTER: AtomicU64 = AtomicU64::new(0);
std::fs::create_dir_all(dir).with_context(|| format!("creating {}", dir.display()))?;
let target = dir.join(name);
let temp = dir.join(format!(
".{name}.{}-{}.tmp",
std::process::id(),
COUNTER.fetch_add(1, Ordering::Relaxed)
));
let result = std::fs::write(&temp, bytes)
.and_then(|()| std::fs::rename(&temp, &target))
.with_context(|| format!("writing {}", target.display()));
if result.is_err() {
let _ = std::fs::remove_file(&temp);
}
result?;
Ok(target)
}
+245
View File
@@ -0,0 +1,245 @@
//! Podcast runtime of the TUI: feed HTTP, refresh scheduling and the glue
//! between the shared podcast store and the device-sync log.
//!
//! The data model, identity rules, merge rules and the SQLite store are not
//! defined here: they come from FRID (`music_dht::podcast` and
//! `furumi_library::podcasts::PodcastStore`, file `podcasts.sqlite3`). This
//! module only does what the contract leaves to clients:
//!
//! * [`fetch`] downloads feeds (conditional GET, redirects reported so
//! permanent moves become feed aliases, size and time limits) and covers;
//! * [`refresh`] subscribes and refreshes feeds: it parses them with the
//! shared `music_dht::podcast::feed` parser, ingests them with
//! `PodcastStore::apply_feed` and keeps the local fetch state (validators,
//! errors, back-off);
//! * [`OpLog`] hands store actions the stamps of the device-sync log and
//! appends the operations they return;
//! * [`stream`] plays an episode straight from the publisher through a
//! bounded HTTP Range reader, and [`playback`] resolves the current audio
//! URL and resume position, opens and positions it;
//! * [`progress`] writes resume positions, completions and listening
//! sessions in order on its own thread;
//! * [`publication`] publishes the podcasts the user chose to share to the
//! public discovery overlay (`music_dht::podcast_dht`) and revokes them;
//! * [`discovery`] handles public cards found by search: their order, the
//! "already subscribed" mark, an episode preview read from the feed and
//! subscribing from a card.
//!
//! Only RSS metadata is stored. Audio stays on the publisher's server.
pub mod discovery;
pub mod fetch;
pub mod playback;
pub mod progress;
pub mod publication;
pub mod refresh;
pub mod stream;
#[cfg(test)]
mod discovery_tests;
#[cfg(test)]
mod playback_tests;
#[cfg(test)]
mod publication_tests;
#[cfg(test)]
mod stream_tests;
#[cfg(test)]
mod test_server;
#[cfg(test)]
mod tests;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use anyhow::{Result, anyhow};
use furumi_library::podcasts::{
LEGACY_PROTOTYPE_SCHEMA_VERSION, PODCAST_DB_FILE, PodcastListFilter, PodcastLocalOp,
PodcastStore, PodcastStoreError, StampSource,
};
pub use fetch::Fetcher;
use refresh::Services;
/// Appends podcast operations to the device-sync log.
///
/// [`OpLog::record`] gives `action` a [`StampSource`] that reserves stamps
/// in the log. The action runs a `PodcastStore` local action and returns the
/// operations it emitted; they are appended with exactly those stamps.
pub trait OpLog: Send + Sync {
fn record(
&self,
action: &mut dyn FnMut(&mut dyn StampSource) -> Result<Vec<PodcastLocalOp>>,
) -> Result<()>;
}
/// The podcast store file. It is the file the prototype podcast build
/// used, so an existing prototype database is migrated in place.
pub fn db_path() -> Result<PathBuf> {
let dirs = crate::config::project_dirs()
.ok_or_else(|| anyhow!("no home directory for podcast data"))?;
Ok(dirs.data_dir().join(PODCAST_DB_FILE))
}
/// Replaceable cache of downloaded podcast covers.
pub fn covers_dir() -> Result<PathBuf> {
let dirs = crate::config::project_dirs()
.ok_or_else(|| anyhow!("no cache directory for podcast covers"))?;
Ok(dirs.cache_dir().join("podcasts").join("covers"))
}
/// Opens the podcast store at `db_path` and builds the feed client.
///
/// `PodcastStore::open` migrates a prototype database in place and refuses,
/// without writing anything, a database from a newer Furumi or a file that
/// is not a podcast database. Blocking: call it on the blocking pool.
pub fn open_services(db_path: &Path, covers_dir: PathBuf, log: Arc<dyn OpLog>) -> Result<Services> {
// The import commits inside `PodcastStore::open`; dropping its
// validators happens afterwards. A marker written before the import and
// removed only once every podcast was handled makes that step resumable
// after a crash or a failed write in between.
let marker = validators_marker(db_path);
let mut pending = marker.is_file();
if is_prototype_database(db_path) {
if let Err(err) = std::fs::write(&marker, b"") {
tracing::warn!("cannot record the pending prototype feed checks: {err}");
}
pending = true;
}
let store = PodcastStore::open(db_path)?;
tracing::info!(path = %db_path.display(), "podcast store opened");
if pending && forget_prototype_validators(&store) {
match std::fs::remove_file(&marker) {
Ok(()) => {}
Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
Err(err) => tracing::warn!("cannot remove {}: {err}", marker.display()),
}
}
match store.legacy_quarantine() {
Ok(entries) if !entries.is_empty() => tracing::warn!(
count = entries.len(),
"some prototype podcast rows could not be imported; they are kept in the legacy_* tables"
),
Ok(_) => {}
Err(err) => tracing::debug!("reading the podcast import quarantine failed: {err:#}"),
}
let confirmations =
publication::ShareConfirmations::open(publication::confirmations_path(db_path));
Ok(Services {
store: Arc::new(store),
fetcher: Arc::new(Fetcher::new(covers_dir)?),
log,
confirmations: Arc::new(confirmations),
})
}
/// Whether `path` is a database of the prototype podcast build, which
/// `PodcastStore::open` is about to import. Read-only; any doubt is "no".
fn is_prototype_database(path: &Path) -> bool {
if !path.is_file() {
return false;
}
let flags =
rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY | rusqlite::OpenFlags::SQLITE_OPEN_NO_MUTEX;
rusqlite::Connection::open_with_flags(path, flags)
.and_then(|conn| conn.query_row("PRAGMA user_version", [], |row| row.get::<_, i64>(0)))
.is_ok_and(|version| version == LEGACY_PROTOTYPE_SCHEMA_VERSION)
}
/// Marker next to the podcast store: the validators imported from a
/// prototype database still have to be dropped
/// ([`forget_prototype_validators`]).
fn validators_marker(db_path: &Path) -> PathBuf {
let mut name = db_path
.file_name()
.map(std::ffi::OsStr::to_os_string)
.unwrap_or_default();
name.push(".full-check-pending");
db_path.with_file_name(name)
}
/// Drops the HTTP validators imported from a prototype database. Returns
/// whether every podcast was handled (otherwise it runs again at the next
/// start).
///
/// The prototype stored no seasons, episode numbers or episode types, and
/// its GUID-less episodes stay provisional until a feed is parsed again. With
/// the imported `ETag` / `Last-Modified` the first check would be answered
/// "304 Not Modified" and the feed never parsed while it does not change, so
/// a finished series would never show its seasons. Without them the first
/// check downloads and applies the feed. The fetch state is local (never
/// synced).
///
/// Only the public fetch-state API exists for this: the validators are
/// cleared by recording a success at the last check, keeping the next check
/// time, and an imported error is recorded again as many times as it was
/// counted, so the back-off stays as imported. The one side effect is that a
/// podcast imported with an error gets a last success time (its last check),
/// which is not shown while the error is. Running this again only costs one
/// unconditional feed download per podcast. Contract gap: FRID's prototype
/// import should not carry the validators over.
fn forget_prototype_validators(store: &PodcastStore) -> bool {
let result = (|| -> Result<usize> {
let mut cleared = 0;
for podcast in store.list_podcasts(PodcastListFilter::All)? {
let id = &podcast.podcast_id;
let state = store.fetch_state(id)?;
if state.etag.is_none() && state.last_modified.is_none() {
continue;
}
let checked = state
.last_success_at_ms
.or(state.checked_at_ms)
.unwrap_or(0);
store.record_fetch_success(id, checked, None, None, state.next_check_at_ms)?;
if let Some(error) = &state.last_error {
for _ in 0..state.consecutive_failures.max(1) {
store.record_fetch_failure(
id,
state.checked_at_ms.unwrap_or(checked),
error,
state.next_check_at_ms,
)?;
}
}
cleared += 1;
}
Ok(cleared)
})();
match result {
Ok(cleared) => {
if cleared > 0 {
tracing::info!(
cleared,
"imported podcasts get a full first feed check (prototype validators dropped)"
);
}
true
}
Err(err) => {
tracing::warn!(
"dropping imported podcast validators failed (retried at the next start): {err:#}"
);
false
}
}
}
/// A readable reason why the store did not open; the typed store errors
/// already say that the file was left unchanged.
pub fn describe_open_error(err: &anyhow::Error) -> String {
match err.downcast_ref::<PodcastStoreError>() {
Some(store_error) => store_error.to_string(),
None => format!("{err:#}"),
}
}
/// Runs blocking store or filesystem work off the Tokio workers.
pub(crate) async fn blocking<T, F>(work: F) -> Result<T>
where
T: Send + 'static,
F: FnOnce() -> Result<T> + Send + 'static,
{
tokio::task::spawn_blocking(work)
.await
.map_err(|err| anyhow!("background task failed: {err}"))?
}
+291
View File
@@ -0,0 +1,291 @@
//! Preparing an episode for playback: resolve its current audio URL and
//! resume position from the store, open the HTTP stream, decode it and
//! position it, all off the UI and audio threads.
//!
//! The queue item ([`PodcastEpisodeRef`]) carries the URL that was current
//! when the episode was queued (or received); the store is asked again at
//! play time, so a feed refresh that changed the episode's audio URL is
//! picked up. When the publisher answers a stale URL with a client error,
//! the feed is refreshed once and the episode retried with the address the
//! feed now lists for the same episode id.
use std::sync::Arc;
use std::time::Duration;
use anyhow::{Context as _, Result, anyhow};
use furumi_library::podcasts::PodcastStore;
use music_dht::podcast::{PodcastEpisodeRef, reaches_completion};
use rodio::Source as _;
use super::blocking;
use super::refresh::{self, Services};
use super::stream::{self, CancelToken, Cancelled, StreamEnd, StreamProbe, StreamStatusError};
use crate::player::{DecodedSource, decode_source_with};
/// Where playback of an episode starts.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StartAt {
/// Ordinary Play: the saved resume position (the beginning for a new
/// or completed episode).
Resume,
/// An exact position (handoff, restarting the same item).
Position { ms: i64 },
/// "Start over": from the beginning, recorded as an explicit restart.
Restart,
}
/// An episode ready to hand to the audio thread.
pub struct PreparedEpisode {
/// The episode as the store knows it now (current URL and duration), or
/// the queued reference when the store does not know it.
pub episode: PodcastEpisodeRef,
pub source: DecodedSource,
/// Position the source was moved to.
pub start_ms: i64,
/// Duration from the decoder, else the one the feed announced.
pub duration_ms: Option<i64>,
/// `duration_ms` was measured by the decoder (container header, frame
/// count or file size); otherwise it is only the feed's announcement,
/// which is often off (rounded `itunes:duration`, inserted ads).
pub duration_measured: bool,
/// The server allows seeking (it sent the file size).
pub seekable: bool,
/// How the stream ended, once it did.
pub probe: StreamProbe,
}
impl std::fmt::Debug for PreparedEpisode {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("PreparedEpisode")
.field("episode", &self.episode.episode_id)
.field("start_ms", &self.start_ms)
.field("duration_ms", &self.duration_ms)
.finish_non_exhaustive()
}
}
/// The episode cannot start where it should, so it does not start at all:
/// the saved position is kept and the user is told why.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CannotResume {
pub position_ms: i64,
}
impl std::fmt::Display for CannotResume {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(
f,
"the server does not allow seeking in this episode, so it cannot continue at {}; \
the saved position is kept (use \"start over\" to play it from the beginning)",
format_position(self.position_ms)
)
}
}
impl std::error::Error for CannotResume {}
fn format_position(ms: i64) -> String {
let secs = ms.max(0) / 1_000;
let (hours, minutes, seconds) = (secs / 3_600, secs / 60 % 60, secs % 60);
if hours > 0 {
format!("{hours}:{minutes:02}:{seconds:02}")
} else {
format!("{minutes}:{seconds:02}")
}
}
/// The episode reference and start position to use, from the store when it
/// knows the episode. Blocking.
pub fn resolve(
store: Option<&PodcastStore>,
queued: &PodcastEpisodeRef,
start: StartAt,
) -> Result<(PodcastEpisodeRef, i64)> {
let current = match store {
Some(store) => store.episode_ref(&queued.episode_id)?,
None => None,
};
let mut episode = current.unwrap_or_else(|| queued.clone());
// Keep the greatest generation either side has seen (handoff).
episode.progress_generation = episode.progress_generation.max(queued.progress_generation);
let start_ms = match start {
StartAt::Resume => match store {
Some(store) => store.resume_position_ms(&queued.episode_id)?,
None => 0,
},
StartAt::Position { ms } => ms.max(0),
StartAt::Restart => 0,
};
Ok((episode, start_ms))
}
/// Share of a feed-announced duration (percent) that a stream of unknown
/// size must have played before its clean close counts as its end.
const FEED_DURATION_END_PERCENT: i64 = 80;
/// Whether the end of an episode's stream means it was played to the end:
///
/// * a stream that ended where the server said it would is the end;
/// * a stream that failed (connection lost, URL expired, outage) only
/// counts when it failed within the shared completion window;
/// * a stream of unknown size that closed cleanly (where an early close
/// looks like the end) counts when the position is within the completion
/// window of a duration the decoder measured. A duration that only the
/// feed announced is a hint: then reaching [`FEED_DURATION_END_PERCENT`]
/// of it is enough, and with no duration at all the close is the end.
pub fn played_to_the_end(
end: StreamEnd,
position_ms: i64,
duration_ms: Option<i64>,
duration_measured: bool,
) -> bool {
let near_end = duration_ms.is_some() && reaches_completion(position_ms, duration_ms);
match end {
StreamEnd::Complete => true,
StreamEnd::Failed => near_end,
StreamEnd::Unknown => match duration_ms {
None => true,
Some(_) if duration_measured => near_end,
Some(ms) => {
near_end
|| position_ms.saturating_mul(100)
>= ms.saturating_mul(FEED_DURATION_END_PERCENT)
}
},
}
}
/// Opens, decodes and positions the audio of `episode`. Blocking (network).
/// Stops with [`Cancelled`] once `cancel` fires: a superseded resume does
/// not keep downloading up to its offset.
pub fn open_at(
episode: &PodcastEpisodeRef,
start_ms: i64,
cancel: &CancelToken,
) -> Result<PreparedEpisode> {
let opened = stream::open_with(&episode.audio_url, cancel.clone())?;
let seekable = opened.seekable;
let probe = opened.probe.clone();
// Coarse seeking maps a time to a byte offset (one Range request)
// instead of decoding everything before it.
let coarse_seek = seekable && opened.byte_len.is_some();
let mime = opened.mime_type.clone().or_else(|| episode.mime.clone());
let mut source = decode_source_with(
Box::new(opened.reader),
opened.byte_len,
mime.as_deref(),
seekable,
coarse_seek,
)
.map_err(|err| {
if cancel.is_cancelled() {
anyhow!(Cancelled)
} else {
anyhow!("cannot decode the episode audio: {err}")
}
})?;
if start_ms > 0 {
if !seekable {
return Err(CannotResume {
position_ms: start_ms,
}
.into());
}
let target = Duration::from_millis(start_ms as u64);
if let Err(err) = source.try_seek(target) {
if cancel.is_cancelled() {
return Err(Cancelled.into());
}
tracing::warn!(%err, "seeking a podcast stream failed");
return Err(CannotResume {
position_ms: start_ms,
}
.into());
}
}
let measured = source
.total_duration()
.and_then(|duration| i64::try_from(duration.as_millis()).ok())
.filter(|ms| *ms > 0);
Ok(PreparedEpisode {
episode: episode.clone(),
source,
start_ms,
duration_ms: measured.or(episode.duration_ms),
duration_measured: measured.is_some(),
seekable,
probe,
})
}
/// [`resolve`] + [`open_at`], refreshing the feed once when the audio URL
/// answers with a client error (moved or expired file).
pub async fn prepare(
services: Option<Services>,
queued: PodcastEpisodeRef,
start: StartAt,
now_ms: i64,
cancel: CancelToken,
) -> Result<PreparedEpisode> {
let store = services
.as_ref()
.map(|services| Arc::clone(&services.store));
let lookup = queued.clone();
let (episode, start_ms) = blocking(move || resolve(store.as_deref(), &lookup, start)).await?;
let attempt = episode.clone();
let attempt_cancel = cancel.clone();
let error = match blocking(move || open_at(&attempt, start_ms, &attempt_cancel)).await {
Ok(prepared) => return Ok(prepared),
Err(error) => error,
};
if cancel.is_cancelled() {
return Err(Cancelled.into());
}
let stale = error
.downcast_ref::<StreamStatusError>()
.is_some_and(|status| status.url_is_stale());
let Some(services) = services.filter(|_| stale) else {
return Err(error);
};
let store = Arc::clone(&services.store);
let podcast_id = episode.podcast_id.clone();
let feed_url = blocking(move || {
Ok(store
.podcast(&podcast_id)?
.map(|summary| summary.meta.feed_url))
})
.await?;
let Some(feed_url) = feed_url else {
return Err(error);
};
tracing::info!(
episode = %episode.episode_id,
"episode audio unavailable; checking the feed for a new address"
);
if let Err(err) = refresh::refresh(&services, &episode.podcast_id, &feed_url, now_ms).await {
tracing::warn!("refreshing the feed of an unavailable episode failed: {err:#}");
return Err(error);
}
let store = Arc::clone(&services.store);
let lookup = queued.clone();
let (fresh, _) = blocking(move || resolve(Some(&store), &lookup, StartAt::Restart)).await?;
if fresh.audio_url == episode.audio_url {
return Err(error).context("the feed lists the same audio address");
}
if cancel.is_cancelled() {
return Err(Cancelled.into());
}
blocking(move || open_at(&fresh, start_ms, &cancel)).await
}
/// Message for a failed start; the URL never appears (it may carry a
/// private token).
pub fn describe_failure(err: &anyhow::Error) -> String {
if err.downcast_ref::<Cancelled>().is_some() {
return Cancelled.to_string();
}
if let Some(cannot) = err.downcast_ref::<CannotResume>() {
return cannot.to_string();
}
format!("{err:#}")
}
+836
View File
@@ -0,0 +1,836 @@
//! Episode playback preparation and durable progress, against a local HTTP
//! server and a temp-dir store (no internet, no audio device).
use std::sync::PoisonError;
use std::sync::mpsc::{Receiver, RecvTimeoutError};
use std::time::Duration;
use furumi_library::podcasts::{EpisodeQuery, PodcastStore};
use music_dht::podcast::{
EpisodeId, PodcastEpisodeRef, PodcastId, ProgressStatus, reaches_completion,
};
use super::playback::{self, CannotResume, StartAt};
use super::progress::{ProgressCommand, ProgressEvent, ProgressWriter};
use super::refresh::{Services, refresh, subscribe};
use super::stream::{CancelToken, StreamEnd};
use super::test_server::{Route, WAV_RATE, wav};
use super::tests::{Fixture, NOW, fixture, rss};
const MINUTE_MS: i64 = 60_000;
/// Subscribes the fixture to a feed with episodes `a` and `b` and returns
/// the podcast and the reference of episode `a`.
async fn subscribed(f: &Fixture) -> (PodcastId, PodcastEpisodeRef) {
f.server.set(
"/feed.xml",
Route::new(
rss(&[("a", "Pilot"), ("b", "Second")]),
"application/rss+xml",
),
);
let report = subscribe(&f.services, &f.server.url("/feed.xml"), NOW)
.await
.unwrap();
let episode = episode_ref(&f.services.store, &report.podcast_id, "Pilot");
(report.podcast_id, episode)
}
fn episode_ref(store: &PodcastStore, podcast_id: &PodcastId, title: &str) -> PodcastEpisodeRef {
let item = store
.episodes(&EpisodeQuery::new(podcast_id.clone()))
.unwrap()
.into_iter()
.find(|item| item.episode.title == title)
.expect("episode in the catalog");
store
.episode_ref(&item.episode.episode_id)
.unwrap()
.unwrap()
}
/// A progress writer whose events can be awaited.
struct Writer {
writer: ProgressWriter,
events: Receiver<ProgressEvent>,
}
impl Writer {
fn spawn(services: &Services) -> Writer {
let (tx, events) = std::sync::mpsc::channel();
let tx = std::sync::Mutex::new(tx);
let writer = ProgressWriter::spawn(services.clone(), move |event| {
let _ = tx
.lock()
.unwrap_or_else(PoisonError::into_inner)
.send(event);
})
.unwrap();
Writer { writer, events }
}
fn send(&self, command: ProgressCommand) {
self.writer.send(command);
}
/// The next event (the writer handles commands in order).
fn next(&self) -> ProgressEvent {
match self.events.recv_timeout(Duration::from_secs(10)) {
Ok(event) => event,
Err(RecvTimeoutError::Timeout) => panic!("no progress event"),
Err(RecvTimeoutError::Disconnected) => panic!("writer stopped"),
}
}
fn saved(&self) -> music_dht::podcast::ProgressRecord {
match self.next() {
ProgressEvent::Saved(record) => record,
other => panic!("expected a save, got {other:?}"),
}
}
fn close(mut self) {
assert!(self.writer.close(Duration::from_secs(10)));
}
}
fn begin(
playback: u64,
episode: &PodcastEpisodeRef,
position_ms: i64,
restart: bool,
) -> ProgressCommand {
ProgressCommand::Begin {
playback,
episode: Box::new(episode.clone()),
session_id: format!("session-{playback}"),
position_ms,
restart,
now_ms: NOW,
}
}
fn resume(store: &PodcastStore, id: &EpisodeId) -> (i64, ProgressStatus) {
let progress = store.progress(id).unwrap().expect("progress");
(store.resume_position_ms(id).unwrap(), progress.status)
}
#[tokio::test]
async fn resume_position_survives_restarts_and_late_checkpoints_lose() {
let f = fixture();
let (_, episode) = subscribed(&f).await;
let store = &f.services.store;
let id = &episode.episode_id;
// First run: play, save periodically, quit.
let first = Writer::spawn(&f.services);
first.send(begin(1, &episode, 0, false));
let started = first.saved();
assert_eq!(started.status, ProgressStatus::InProgress);
first.send(ProgressCommand::Checkpoint {
playback: 1,
position_ms: 10 * MINUTE_MS,
});
assert_eq!(
first.saved().generation,
started.generation,
"checkpoints keep it"
);
assert_eq!(
resume(store, id),
(10 * MINUTE_MS, ProgressStatus::InProgress)
);
// "Start over" in a later run takes a newer generation…
let second = Writer::spawn(&f.services);
second.send(begin(2, &episode, 0, true));
let restarted = second.saved();
assert!(restarted.generation > started.generation);
assert_eq!(resume(store, id), (0, ProgressStatus::InProgress));
// …so a late checkpoint of the old session loses, whatever its clock.
first.send(ProgressCommand::Checkpoint {
playback: 1,
position_ms: 20 * MINUTE_MS,
});
match first.next() {
ProgressEvent::Superseded { current } => assert_eq!(current.position_ms, 0),
other => panic!("expected supersede, got {other:?}"),
}
assert_eq!(resume(store, id), (0, ProgressStatus::InProgress));
// The old session no longer writes, not even when it ends.
first.send(ProgressCommand::End {
playback: 1,
position_ms: 21 * MINUTE_MS,
listened_ms: 0,
now_ms: NOW + 1,
});
assert!(matches!(first.next(), ProgressEvent::Ended { .. }));
first.close();
assert_eq!(resume(store, id), (0, ProgressStatus::InProgress));
// The new session saves normally, including a seek backwards.
second.send(ProgressCommand::Checkpoint {
playback: 2,
position_ms: 5 * MINUTE_MS,
});
second.saved();
second.send(ProgressCommand::Seek {
playback: 2,
position_ms: MINUTE_MS,
});
let seeked = second.saved();
assert!(
seeked.generation > restarted.generation,
"a seek is explicit"
);
assert_eq!(resume(store, id), (MINUTE_MS, ProgressStatus::InProgress));
second.send(ProgressCommand::End {
playback: 2,
position_ms: MINUTE_MS + 2_000,
listened_ms: 2_000,
now_ms: NOW + 2,
});
second.saved();
assert!(matches!(second.next(), ProgressEvent::Ended { .. }));
second.close();
assert_eq!(
resume(store, id),
(MINUTE_MS + 2_000, ProgressStatus::InProgress)
);
// The sync log carries every write, in order.
let kinds = f.log.kinds();
assert_eq!(kinds[0], "podcast_subscription_set");
assert!(
kinds[1..].iter().all(|kind| kind == "podcast_progress_set"),
"{kinds:?}"
);
}
#[tokio::test]
async fn completion_counts_once_and_short_sessions_stay_out_of_history() {
let f = fixture();
let (_, episode) = subscribed(&f).await;
let store = &f.services.store;
let id = &episode.episode_id;
let duration = episode.duration_ms.expect("the feed has a duration");
assert_eq!(duration, 45 * MINUTE_MS);
let near_end = duration - 20_000;
assert!(reaches_completion(near_end, Some(duration)));
// A short listen: progress is saved, history is not.
let writer = Writer::spawn(&f.services);
writer.send(begin(1, &episode, 0, false));
writer.saved();
writer.send(ProgressCommand::End {
playback: 1,
position_ms: 5_000,
listened_ms: 5_000,
now_ms: NOW + 5_000,
});
writer.saved();
assert!(matches!(writer.next(), ProgressEvent::Ended { .. }));
assert!(store.listen_history(None, 10).unwrap().is_empty());
// A full listen completes the episode once, even if the end is
// reported twice and the session ends afterwards.
writer.send(begin(2, &episode, 5_000, false));
writer.saved();
for _ in 0..2 {
writer.send(ProgressCommand::Complete {
playback: 2,
position_ms: near_end,
listened_ms: near_end - 5_000,
now_ms: NOW + duration,
});
}
let completed = writer.saved();
assert_eq!(completed.status, ProgressStatus::Completed);
writer.send(ProgressCommand::End {
playback: 2,
position_ms: duration,
listened_ms: duration - 5_000,
now_ms: NOW + duration + 20_000,
});
assert!(matches!(writer.next(), ProgressEvent::Ended { .. }));
writer.close();
assert_eq!(
resume(store, id),
(0, ProgressStatus::Completed),
"Play starts over"
);
assert_eq!(store.completed_listen_count(id).unwrap(), 1);
let history = store.listen_history(None, 10).unwrap();
assert_eq!(history.len(), 1);
assert!(history[0].session.completed);
assert_eq!(history[0].session.listened_ms, duration - 5_000);
}
#[tokio::test]
async fn marking_played_while_playing_stops_checkpoints_until_the_next_seek() {
let f = fixture();
let (_, episode) = subscribed(&f).await;
let store = &f.services.store;
let id = &episode.episode_id;
let writer = Writer::spawn(&f.services);
writer.send(begin(1, &episode, 0, false));
writer.saved();
writer.send(ProgressCommand::SetPlayed {
episode_id: id.clone(),
played: true,
});
assert_eq!(writer.saved().status, ProgressStatus::Completed);
assert!(matches!(
writer.next(),
ProgressEvent::PlayedSet {
played: true,
result: Ok(())
}
));
writer.send(ProgressCommand::Checkpoint {
playback: 1,
position_ms: 90_000,
});
assert!(matches!(writer.next(), ProgressEvent::Superseded { .. }));
assert_eq!(resume(store, id).1, ProgressStatus::Completed);
// Seeking is the user's explicit choice to keep listening here.
writer.send(ProgressCommand::Seek {
playback: 1,
position_ms: 30_000,
});
assert_eq!(writer.saved().status, ProgressStatus::InProgress);
assert_eq!(resume(store, id), (30_000, ProgressStatus::InProgress));
writer.close();
}
/// Serves a position-coded WAV for episode `a` and returns its seconds.
fn serve_audio(f: &Fixture, route: impl FnOnce(Route) -> Route, seconds: u32) -> u32 {
f.server
.set("/audio/a.mp3", route(Route::new(wav(seconds), "audio/wav")));
seconds
}
/// Seconds marker of the next decoded sample (see `test_server::wav`).
fn second_marker(source: &mut crate::player::DecodedSource) -> i64 {
let sample = source.next().expect("a sample");
(sample * 32_768.0 / 40.0).round() as i64
}
/// The source plays from `second`. A seek may land up to one decoder packet
/// early (1024 frames, 0.128 s at 8 kHz) in the previous second.
fn assert_starts_at(source: &mut crate::player::DecodedSource, second: i64) {
let marker = second_marker(source);
assert!(
marker == second || marker == second - 1,
"starts in second {marker}, expected {second}"
);
// A quarter of a second later it is exactly there.
let marker = (0..WAV_RATE / 4)
.map(|_| second_marker(source))
.last()
.unwrap();
assert_eq!(marker, second);
}
async fn save_position(services: &Services, episode: &PodcastEpisodeRef, position_ms: i64) {
let writer = Writer::spawn(services);
writer.send(begin(99, episode, position_ms, false));
writer.saved();
writer.close();
}
#[tokio::test]
async fn play_resumes_at_the_saved_position_with_a_range_request() {
let f = fixture();
let (_, episode) = subscribed(&f).await;
let seconds = serve_audio(&f, |route| route, 12 * 60);
save_position(&f.services, &episode, 11 * MINUTE_MS).await;
let prepared = playback::prepare(
Some(f.services.clone()),
episode.clone(),
StartAt::Resume,
NOW,
CancelToken::never(),
)
.await
.unwrap();
assert_eq!(prepared.start_ms, 11 * MINUTE_MS);
assert_eq!(prepared.duration_ms, Some(i64::from(seconds) * 1_000));
let mut source = prepared.source;
assert_starts_at(&mut source, 11 * 60);
// The far seek became a ranged request instead of a full download.
let byte = 11 * 60 * WAV_RATE as usize * 2;
assert!(
f.server.ranges("/audio/a.mp3").iter().any(|range| range
.as_deref()
.and_then(|range| range.strip_prefix("bytes="))
.and_then(|range| range.trim_end_matches('-').parse::<usize>().ok())
.is_some_and(|start| start + 4_096 >= byte && start <= byte + 4_096)),
"{:?}",
f.server.ranges("/audio/a.mp3")
);
// "Start over" ignores the saved position.
let restarted = playback::prepare(
Some(f.services.clone()),
episode,
StartAt::Restart,
NOW,
CancelToken::never(),
)
.await
.unwrap();
assert_eq!(restarted.start_ms, 0);
let mut source = restarted.source;
assert_eq!(second_marker(&mut source), 0);
}
#[tokio::test]
async fn a_server_without_range_support_still_resumes_at_the_right_place() {
let f = fixture();
let (_, episode) = subscribed(&f).await;
serve_audio(&f, Route::no_ranges, 30);
save_position(&f.services, &episode, 20_000).await;
let prepared = playback::prepare(
Some(f.services.clone()),
episode,
StartAt::Resume,
NOW,
CancelToken::never(),
)
.await
.unwrap();
assert_eq!(prepared.start_ms, 20_000);
let mut source = prepared.source;
assert_starts_at(&mut source, 20);
assert!(
f.server
.ranges("/audio/a.mp3")
.iter()
.skip(1)
.all(Option::is_none),
"no ranges are sent to a server that ignores them"
);
}
#[tokio::test]
async fn an_unseekable_stream_does_not_pretend_to_resume() {
let f = fixture();
let (_, episode) = subscribed(&f).await;
serve_audio(&f, |route| route.no_ranges().no_length(), 30);
save_position(&f.services, &episode, 20_000).await;
let err = playback::prepare(
Some(f.services.clone()),
episode.clone(),
StartAt::Resume,
NOW,
CancelToken::never(),
)
.await
.expect_err("cannot resume");
assert_eq!(
err.downcast_ref::<CannotResume>(),
Some(&CannotResume {
position_ms: 20_000
})
);
assert!(playback::describe_failure(&err).contains("0:20"));
// The saved position is untouched, and "start over" still plays.
let store = &f.services.store;
assert_eq!(
store.resume_position_ms(&episode.episode_id).unwrap(),
20_000
);
let prepared = playback::prepare(
Some(f.services.clone()),
episode,
StartAt::Restart,
NOW,
CancelToken::never(),
)
.await
.unwrap();
assert_eq!(prepared.start_ms, 0);
}
#[tokio::test]
async fn the_audio_url_comes_from_the_feed_at_play_time() {
let f = fixture();
let (podcast_id, queued) = subscribed(&f).await;
// The publisher moved the file and the feed already says so.
f.server.set(
"/feed.xml",
Route::new(
rss(&[("a", "Pilot"), ("b", "Second")]).pipe_replace("/audio/a.mp3", "/audio/a-v2.mp3"),
"application/rss+xml",
),
);
let url = f
.services
.store
.podcast(&podcast_id)
.unwrap()
.unwrap()
.meta
.feed_url;
refresh(&f.services, &podcast_id, &url, NOW + 1)
.await
.unwrap();
f.server
.set("/audio/a-v2.mp3", Route::new(wav(5), "audio/wav"));
// The queue item still has the old URL; the store's is used.
assert!(queued.audio_url.ends_with("/audio/a.mp3"));
let prepared = playback::prepare(
Some(f.services.clone()),
queued.clone(),
StartAt::Resume,
NOW,
CancelToken::never(),
)
.await
.unwrap();
assert!(prepared.episode.audio_url.ends_with("/audio/a-v2.mp3"));
assert!(f.server.requests("/audio/a.mp3").is_empty());
assert_eq!(
prepared.episode.episode_id, queued.episode_id,
"same episode"
);
}
#[tokio::test]
async fn a_stale_audio_url_refreshes_the_feed_once_and_retries() {
let f = fixture();
let (_, queued) = subscribed(&f).await;
// The old file is gone (404) and only the feed knows the new one.
f.server.set(
"/feed.xml",
Route::new(
rss(&[("a", "Pilot"), ("b", "Second")]).pipe_replace("/audio/a.mp3", "/audio/a-v3.mp3"),
"application/rss+xml",
),
);
f.server
.set("/audio/a-v3.mp3", Route::new(wav(5), "audio/wav"));
let prepared = playback::prepare(
Some(f.services.clone()),
queued.clone(),
StartAt::Resume,
NOW,
CancelToken::never(),
)
.await
.unwrap();
assert!(prepared.episode.audio_url.ends_with("/audio/a-v3.mp3"));
assert_eq!(f.server.requests("/audio/a.mp3").len(), 1);
assert_eq!(
f.server.requests("/feed.xml").len(),
2,
"one extra feed check"
);
// Without a newer address the original error is reported, once.
f.server.set(
"/audio/a-v3.mp3",
Route::new("gone", "text/plain").status(410),
);
let err = playback::prepare(
Some(f.services.clone()),
queued,
StartAt::Resume,
NOW,
CancelToken::never(),
)
.await
.expect_err("still unavailable");
assert!(format!("{err:#}").contains("410"), "{err:#}");
assert_eq!(f.server.requests("/feed.xml").len(), 3);
}
#[tokio::test]
async fn without_a_store_the_queued_reference_plays_from_the_start() {
let f = fixture();
let (_, episode) = subscribed(&f).await;
serve_audio(&f, |route| route, 5);
save_position(&f.services, &episode, 3_000).await;
let prepared = playback::prepare(None, episode, StartAt::Resume, NOW, CancelToken::never())
.await
.unwrap();
assert_eq!(prepared.start_ms, 0);
}
trait PipeReplace {
fn pipe_replace(self, from: &str, to: &str) -> Vec<u8>;
}
impl PipeReplace for Vec<u8> {
fn pipe_replace(self, from: &str, to: &str) -> Vec<u8> {
String::from_utf8(self)
.unwrap()
.replace(from, to)
.into_bytes()
}
}
/// Decodes `source` to its end, as the audio thread would; returns the
/// position reached (mono samples of `test_server::wav`).
fn play_out(source: &mut crate::player::DecodedSource) -> i64 {
let mut samples = 0i64;
while source.next().is_some() {
samples += 1;
}
samples * 1_000 / i64::from(WAV_RATE)
}
/// Byte offset of second `second` in `test_server::wav`.
fn wav_offset(second: u32) -> usize {
44 + (second * WAV_RATE * 2) as usize
}
#[tokio::test]
async fn a_lost_connection_does_not_complete_the_episode_and_keeps_its_position() {
let f = fixture();
let (_, episode) = subscribed(&f).await;
// Two minutes of audio; the server stops sending after 30 s for good.
serve_audio(&f, |route| route.cut(wav_offset(30), usize::MAX), 120);
let prepared = playback::prepare(
Some(f.services.clone()),
episode.clone(),
StartAt::Resume,
NOW,
CancelToken::never(),
)
.await
.unwrap();
let writer = Writer::spawn(&f.services);
writer.send(begin(1, &episode, 0, false));
writer.saved();
let mut source = prepared.source;
// The decoder ends once the stalled read gives up (STARVE_TIMEOUT).
let position_ms = play_out(&mut source);
assert!(
(29_000..=30_500).contains(&position_ms),
"stopped at {position_ms} ms"
);
assert_eq!(prepared.probe.end(), StreamEnd::Failed);
assert_eq!(prepared.duration_ms, Some(120_000));
assert!(!playback::played_to_the_end(
prepared.probe.end(),
position_ms,
prepared.duration_ms,
prepared.duration_measured
));
// What the runtime then saves: the last position, not a completion.
writer.send(ProgressCommand::End {
playback: 1,
position_ms,
listened_ms: position_ms,
now_ms: NOW + 1,
});
while !matches!(writer.next(), ProgressEvent::Ended { .. }) {}
writer.close();
let store = &f.services.store;
assert_eq!(
resume(store, &episode.episode_id),
(position_ms, ProgressStatus::InProgress)
);
assert_eq!(
store.completed_listen_count(&episode.episode_id).unwrap(),
0
);
}
#[tokio::test]
async fn a_stream_of_unknown_length_that_closes_early_is_not_the_end() {
let f = fixture();
let (_, episode) = subscribed(&f).await;
serve_audio(
&f,
|route| route.no_length().cut(wav_offset(30), usize::MAX),
120,
);
let prepared = playback::prepare(
Some(f.services.clone()),
episode.clone(),
StartAt::Restart,
NOW,
CancelToken::never(),
)
.await
.unwrap();
let mut source = prepared.source;
let position_ms = play_out(&mut source);
assert!((29_000..=30_500).contains(&position_ms), "{position_ms} ms");
// A closed connection looks like the end of the file here...
assert_eq!(prepared.probe.end(), StreamEnd::Unknown);
// ...but the duration the decoder read from the header says otherwise.
assert_eq!(prepared.duration_ms, Some(120_000));
assert!(prepared.duration_measured);
assert!(!playback::played_to_the_end(
StreamEnd::Unknown,
position_ms,
Some(120_000),
true
));
assert!(playback::played_to_the_end(
StreamEnd::Unknown,
119_000,
Some(120_000),
true
));
// A duration only the feed announced is a hint: an audio file that ends
// more than the completion window before it still ends there...
assert!(playback::played_to_the_end(
StreamEnd::Unknown,
100_000,
Some(120_000),
false
));
// ...while a close at a quarter of it is still a lost connection.
assert!(!playback::played_to_the_end(
StreamEnd::Unknown,
position_ms,
Some(120_000),
false
));
// A whole file with a size is played to its end.
serve_audio(&f, |route| route, 3);
let prepared = playback::prepare(
Some(f.services.clone()),
episode,
StartAt::Restart,
NOW,
CancelToken::never(),
)
.await
.unwrap();
let mut source = prepared.source;
assert_eq!(play_out(&mut source), 3_000);
assert_eq!(prepared.probe.end(), StreamEnd::Complete);
assert!(playback::played_to_the_end(
StreamEnd::Complete,
3_000,
prepared.duration_ms,
prepared.duration_measured
));
// A failure in the last seconds still counts as the end, whatever
// announced the duration; earlier it never does.
for measured in [true, false] {
assert!(playback::played_to_the_end(
StreamEnd::Failed,
119_500,
Some(120_000),
measured
));
assert!(!playback::played_to_the_end(
StreamEnd::Failed,
100_000,
Some(120_000),
measured
));
}
}
/// About `seconds` of silent MPEG-1 Layer III (mono, 44.1 kHz, 128 kbit/s)
/// frames with no Xing/Info header: sent without a size, the decoder
/// cannot measure its duration.
fn mp3_without_header(seconds: u32) -> Vec<u8> {
const FRAME_LEN: usize = 417; // 144 * 128_000 / 44_100
let frames = (u64::from(seconds) * 44_100 / 1_152) as usize;
let mut frame = vec![0u8; FRAME_LEN];
frame[..4].copy_from_slice(&[0xFF, 0xFB, 0x90, 0xC0]);
frame.repeat(frames)
}
/// Decodes `source` to its end; returns the position reached.
fn play_out_any(source: &mut crate::player::DecodedSource) -> i64 {
let per_second = i64::from(source.sample_rate().get()) * i64::from(source.channels().get());
let mut samples = 0i64;
while source.next().is_some() {
samples += 1;
}
samples * 1_000 / per_second
}
/// Without a size from the server and a duration the decoder could
/// measure, only the feed's duration is known, and it may be longer than
/// the audio by more than the completion window. The clean end of the
/// stream then still completes the episode.
#[tokio::test]
async fn a_stream_shorter_than_the_feed_says_completes_at_its_end() {
let f = fixture();
let (_, mut episode) = subscribed(&f).await;
f.server.set(
"/audio/a.mp3",
Route::new(mp3_without_header(100), "audio/mpeg").no_length(),
);
// The feed announces two minutes, 20 s more than the audio.
episode.duration_ms = Some(120_000);
let prepared =
tokio::task::spawn_blocking(move || playback::open_at(&episode, 0, &CancelToken::never()))
.await
.unwrap()
.unwrap();
assert!(!prepared.seekable);
assert!(!prepared.duration_measured, "{:?}", prepared.duration_ms);
assert_eq!(prepared.duration_ms, Some(120_000));
let mut source = prepared.source;
let position_ms = play_out_any(&mut source);
assert!(
(99_000..=100_100).contains(&position_ms),
"{position_ms} ms"
);
assert_eq!(prepared.probe.end(), StreamEnd::Unknown);
assert!(!reaches_completion(position_ms, Some(120_000)));
assert!(playback::played_to_the_end(
prepared.probe.end(),
position_ms,
prepared.duration_ms,
prepared.duration_measured
));
}
#[test]
fn a_superseded_resume_stops_reading_up_to_its_offset() {
let f = fixture();
let rt = tokio::runtime::Runtime::new().unwrap();
let (_, episode) = rt.block_on(subscribed(&f));
// No Range support: resuming at 60 s means reading and discarding
// everything before it (while positioning, or on the first reads after
// it, depending on the format), and this server stalls after 10 s.
serve_audio(
&f,
|route| route.no_ranges().cut(wav_offset(10), usize::MAX),
120,
);
let superseded = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
let flag = std::sync::Arc::clone(&superseded);
let cancel = CancelToken::new(move || flag.load(std::sync::atomic::Ordering::SeqCst));
let started = std::time::Instant::now();
let starting = std::thread::spawn(move || {
let prepared = playback::open_at(&episode, 60_000, &cancel)?;
let mut source = prepared.source;
Ok::<_, anyhow::Error>((source.next(), prepared.probe))
});
std::thread::sleep(Duration::from_millis(300));
superseded.store(true, std::sync::atomic::Ordering::SeqCst);
match starting.join().unwrap() {
Err(err) => assert!(
err.downcast_ref::<super::stream::Cancelled>().is_some(),
"{err:#}"
),
Ok((sample, probe)) => {
assert_eq!(sample, None, "nothing plays after the cancel");
assert_eq!(probe.end(), StreamEnd::Failed);
}
}
// Well before a stalled read would give up by itself.
assert!(
started.elapsed() < super::stream::STARVE_TIMEOUT / 2,
"{:?}",
started.elapsed()
);
}
+488
View File
@@ -0,0 +1,488 @@
//! Durable episode progress: one background thread writes every progress
//! action of this device to the podcast store and the sync log, in order.
//!
//! The rules come from the FRID contract (`music_dht::podcast::state`,
//! `PodcastStore` progress actions); this module only decides *when* to
//! call them:
//!
//! * a playback start is an explicit action (`start_session`, or `restart`
//! for "start over") that takes a new progress generation;
//! * periodic checkpoints, pause and the final save keep the session's
//! generation (`checkpoint`), so a late checkpoint of an older session
//! always loses against a newer explicit action;
//! * a seek is explicit (`seek`) and becomes the session's generation;
//! * reaching the end (`reaches_completion` or the end of the stream) is
//! `complete_session`;
//! * when the store reports a newer generation (`Superseded`), the session
//! stops writing checkpoints until the user's next explicit action;
//! * the listening session itself (`ListenSession`) is recorded at pause,
//! completion and end; the store only keeps sessions that pass the shared
//! history threshold and only when they grew.
//!
//! "Mark played" / "Mark unplayed" go through the same thread so they are
//! ordered with the checkpoints of a playing episode.
//!
//! Writes never happen on the UI or audio thread, and a failed write is
//! reported and logged without stopping playback.
use std::sync::Arc;
use std::sync::mpsc::{Receiver, Sender};
use std::thread::JoinHandle;
use std::time::Duration;
use anyhow::{Result, anyhow};
use furumi_library::podcasts::{
CheckpointOutcome, PodcastLocalOp, PodcastStore, ProgressSession, ProgressWrite, StampSource,
};
use music_dht::podcast::{EpisodeId, ListenSession, PodcastEpisodeRef, ProgressRecord};
use super::OpLog;
use super::refresh::Services;
/// How often a playing episode saves its position.
pub const CHECKPOINT_INTERVAL: Duration = Duration::from_secs(20);
/// What the UI asks the writer to do. `playback` identifies one start of
/// one episode on this device; commands for a playback that is no longer
/// the active one are ignored (they can only arrive late).
#[derive(Debug, Clone)]
pub enum ProgressCommand {
/// Playback actually started at `position_ms`.
Begin {
playback: u64,
episode: Box<PodcastEpisodeRef>,
session_id: String,
position_ms: i64,
/// "Start over" instead of an ordinary start or resume.
restart: bool,
now_ms: i64,
},
/// Periodic save while playing.
Checkpoint { playback: u64, position_ms: i64 },
/// Paused: save the position and the listening session so far.
Pause {
playback: u64,
position_ms: i64,
listened_ms: i64,
now_ms: i64,
},
/// The user moved to `position_ms`.
Seek { playback: u64, position_ms: i64 },
/// The position reached the end of the episode.
Complete {
playback: u64,
position_ms: i64,
listened_ms: i64,
now_ms: i64,
},
/// Playback of this start ended (stop, next item, handoff, exit…).
End {
playback: u64,
position_ms: i64,
listened_ms: i64,
now_ms: i64,
},
/// "Mark played" / "Mark unplayed" from the episode list.
SetPlayed { episode_id: EpisodeId, played: bool },
}
/// What the writer reports back.
#[derive(Debug, Clone, PartialEq)]
pub enum ProgressEvent {
/// The progress register of an episode was written.
Saved(ProgressRecord),
/// A newer explicit action holds the register; this playback stopped
/// saving its position.
Superseded { current: ProgressRecord },
/// A playback ended (its session was recorded when long enough).
Ended { episode_id: EpisodeId },
/// The result of a `SetPlayed` command.
PlayedSet {
played: bool,
result: Result<(), String>,
},
/// A write failed; playback goes on.
Failed(String),
}
/// Handle of the writer thread.
pub struct ProgressWriter {
tx: Option<Sender<ProgressCommand>>,
thread: Option<JoinHandle<()>>,
}
impl ProgressWriter {
pub fn spawn(
services: Services,
on_event: impl Fn(ProgressEvent) + Send + 'static,
) -> Result<ProgressWriter> {
let (tx, rx) = std::sync::mpsc::channel();
let thread = std::thread::Builder::new()
.name("podcast-progress".to_string())
.spawn(move || run(rx, &services.store, services.log.as_ref(), on_event))
.map_err(|err| anyhow!("starting the podcast progress writer: {err}"))?;
Ok(ProgressWriter {
tx: Some(tx),
thread: Some(thread),
})
}
pub fn send(&self, command: ProgressCommand) {
if let Some(tx) = &self.tx
&& tx.send(command).is_err()
{
tracing::warn!("podcast progress writer stopped; a progress update was lost");
}
}
/// Stops accepting commands and waits up to `timeout` for the queued
/// ones to be written. Blocking; used at exit.
pub fn close(&mut self, timeout: Duration) -> bool {
self.tx = None;
let Some(thread) = self.thread.take() else {
return true;
};
let deadline = std::time::Instant::now() + timeout;
while !thread.is_finished() {
if std::time::Instant::now() >= deadline {
tracing::warn!("podcast progress writer did not finish before exit");
return false;
}
std::thread::sleep(Duration::from_millis(10));
}
let _ = thread.join();
true
}
}
/// The playback whose session the writer is maintaining.
struct Active {
playback: u64,
/// `None` when starting the session failed: nothing is written for it.
session: Option<ProgressSession>,
episode: PodcastEpisodeRef,
session_id: String,
started_at_ms: i64,
start_position_ms: i64,
/// A newer generation holds the register: no more checkpoints.
superseded: bool,
/// The register says this session completed the episode (a later seek
/// back makes it "in progress" again).
completed: bool,
/// The session reached the end at least once; it counts as a completed
/// listen whatever happens afterwards.
listen_completed: bool,
}
fn run(
rx: Receiver<ProgressCommand>,
store: &Arc<PodcastStore>,
log: &dyn OpLog,
on_event: impl Fn(ProgressEvent),
) {
let mut writer = Writer {
store,
log,
active: None,
on_event: &on_event,
};
while let Ok(command) = rx.recv() {
writer.handle(command);
}
}
struct Writer<'a, F: Fn(ProgressEvent)> {
store: &'a PodcastStore,
log: &'a dyn OpLog,
active: Option<Active>,
on_event: &'a F,
}
/// Runs a store action through the sync log and returns its value.
fn record<T>(
log: &dyn OpLog,
mut action: impl FnMut(&mut dyn StampSource) -> Result<(T, Vec<PodcastLocalOp>)>,
) -> Result<T> {
let mut value = None;
log.record(&mut |stamps| {
let (result, ops) = action(stamps)?;
value = Some(result);
Ok(ops)
})?;
value.ok_or_else(|| anyhow!("the podcast action did not run"))
}
impl<F: Fn(ProgressEvent)> Writer<'_, F> {
fn emit(&self, event: ProgressEvent) {
(self.on_event)(event);
}
fn fail(&self, what: &str, err: anyhow::Error) {
let message = format!("podcast progress: {what} failed: {err:#}");
tracing::warn!("{message}");
self.emit(ProgressEvent::Failed(message));
}
fn active_mut(&mut self, playback: u64) -> Option<&mut Active> {
self.active
.as_mut()
.filter(|active| active.playback == playback)
}
fn handle(&mut self, command: ProgressCommand) {
match command {
ProgressCommand::Begin {
playback,
episode,
session_id,
position_ms,
restart,
now_ms,
} => self.begin(playback, *episode, session_id, position_ms, restart, now_ms),
ProgressCommand::Checkpoint {
playback,
position_ms,
} => self.checkpoint(playback, position_ms),
ProgressCommand::Pause {
playback,
position_ms,
listened_ms,
now_ms,
} => {
self.checkpoint(playback, position_ms);
self.record_session(playback, position_ms, listened_ms, now_ms);
}
ProgressCommand::Seek {
playback,
position_ms,
} => self.seek(playback, position_ms),
ProgressCommand::Complete {
playback,
position_ms,
listened_ms,
now_ms,
} => {
self.complete(playback, position_ms);
self.record_session(playback, position_ms, listened_ms, now_ms);
}
ProgressCommand::End {
playback,
position_ms,
listened_ms,
now_ms,
} => {
self.checkpoint(playback, position_ms);
self.record_session(playback, position_ms, listened_ms, now_ms);
if let Some(active) = self.active.take_if(|active| active.playback == playback) {
self.emit(ProgressEvent::Ended {
episode_id: active.episode.episode_id,
});
}
}
ProgressCommand::SetPlayed { episode_id, played } => {
let result = self.set_played(&episode_id, played);
if let Err(err) = &result {
tracing::warn!("podcast progress: marking played failed: {err:#}");
}
self.emit(ProgressEvent::PlayedSet {
played,
result: result.map_err(|err| format!("{err:#}")),
});
}
}
}
fn begin(
&mut self,
playback: u64,
episode: PodcastEpisodeRef,
session_id: String,
position_ms: i64,
restart: bool,
now_ms: i64,
) {
let store = self.store;
let carried = episode.progress_generation;
let result = record(self.log, |stamps| {
let write = if restart {
store.restart(stamps, &episode, &session_id)?
} else {
store.start_session(stamps, &episode, &session_id, position_ms, carried)?
};
let op = write.op.clone();
Ok((write, vec![op]))
});
let session = match result {
Ok(write) => {
let session = write.session.clone();
self.emit(ProgressEvent::Saved(write.record));
Some(session)
}
Err(err) => {
self.fail("starting a listening session", err);
None
}
};
self.active = Some(Active {
playback,
session,
episode,
session_id,
started_at_ms: now_ms,
start_position_ms: position_ms,
superseded: false,
completed: false,
listen_completed: false,
});
}
fn checkpoint(&mut self, playback: u64, position_ms: i64) {
let store = self.store;
let log = self.log;
let Some(active) = self.active_mut(playback) else {
return;
};
if active.superseded {
return;
}
let Some(session) = active.session.clone() else {
return;
};
let result = record(log, |stamps| {
let outcome = store.checkpoint(stamps, &session, position_ms)?;
let ops = match &outcome {
CheckpointOutcome::Written(write) => vec![write.op.clone()],
_ => Vec::new(),
};
Ok((outcome, ops))
});
match result {
Ok(CheckpointOutcome::Written(write)) => self.emit(ProgressEvent::Saved(write.record)),
Ok(CheckpointOutcome::Superseded { current }) => {
if let Some(active) = self.active_mut(playback) {
active.superseded = true;
}
tracing::info!(
episode = %current.episode_id,
"a newer progress action took over; this playback stops saving"
);
self.emit(ProgressEvent::Superseded { current });
}
Ok(CheckpointOutcome::AlreadyCompleted { .. }) => {}
Err(err) => self.fail("saving the position", err),
}
}
/// Explicit actions of a running session (seek, completion): they take
/// a new generation and resume saving after a supersede.
fn explicit(
&mut self,
playback: u64,
what: &str,
action: impl Fn(&PodcastStore, &mut dyn StampSource, &ProgressSession) -> Result<ProgressWrite>,
) -> bool {
let store = self.store;
let log = self.log;
let Some(active) = self.active_mut(playback) else {
return false;
};
let Some(session) = active.session.clone() else {
return false;
};
let result = record(log, |stamps| {
let write = action(store, stamps, &session)?;
let op = write.op.clone();
Ok((write, vec![op]))
});
match result {
Ok(write) => {
if let Some(active) = self.active_mut(playback) {
active.session = Some(write.session.clone());
active.superseded = false;
}
self.emit(ProgressEvent::Saved(write.record));
true
}
Err(err) => {
self.fail(what, err);
false
}
}
}
fn seek(&mut self, playback: u64, position_ms: i64) {
if self.explicit(playback, "saving a seek", |store, stamps, session| {
store.seek(stamps, session, position_ms)
}) && let Some(active) = self.active_mut(playback)
{
active.completed = false;
}
}
fn complete(&mut self, playback: u64, position_ms: i64) {
if self
.active_mut(playback)
.is_none_or(|active| active.completed)
{
return;
}
if self.explicit(
playback,
"marking the episode finished",
|store, stamps, session| store.complete_session(stamps, session, position_ms),
) && let Some(active) = self.active_mut(playback)
{
active.completed = true;
active.listen_completed = true;
}
}
/// Records (or grows) the listening session of `playback`.
fn record_session(&mut self, playback: u64, position_ms: i64, listened_ms: i64, now_ms: i64) {
let store = self.store;
let log = self.log;
let Some(active) = self.active_mut(playback) else {
return;
};
let mut session = ListenSession {
session_id: active.session_id.clone(),
episode_id: active.episode.episode_id.clone(),
podcast_id: active.episode.podcast_id.clone(),
device_id: String::new(),
started_at_ms: active.started_at_ms,
ended_at_ms: now_ms.max(active.started_at_ms),
start_position_ms: active.start_position_ms.max(0),
end_position_ms: position_ms.max(0),
listened_ms: listened_ms.max(0),
completed: active.listen_completed,
};
let episode = active.episode.clone();
let result = record(log, |stamps| {
session.device_id = stamps.device_id().to_string();
let op = store.record_listen_session(stamps, &session, Some(&episode))?;
Ok(((), op.into_iter().collect()))
});
if let Err(err) = result {
self.fail("recording the listening session", err);
}
}
fn set_played(&mut self, episode_id: &EpisodeId, played: bool) -> Result<()> {
let episode = self
.store
.episode_ref(episode_id)?
.ok_or_else(|| anyhow!("the episode is no longer in the catalog"))?;
let store = self.store;
let write = record(self.log, |stamps| {
let write = if played {
store.mark_played(stamps, &episode)?
} else {
store.mark_unplayed(stamps, &episode)?
};
let op = write.op.clone();
Ok((write, vec![op]))
})?;
self.emit(ProgressEvent::Saved(write.record));
Ok(())
}
}
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
+430
View File
@@ -0,0 +1,430 @@
//! Subscribing and refreshing feeds.
//!
//! Every function records its HTTP outcome in the store's local fetch state
//! (validators, last error, consecutive failures, next check) so the
//! scheduler never needs its own bookkeeping, and an error never clears the
//! stored catalog.
use std::path::Path;
use std::sync::Arc;
use std::time::Duration;
use anyhow::{Context as _, Result, anyhow, bail};
use furumi_library::podcasts::{FeedRefresh, PodcastStore};
use music_dht::podcast::feed::{ParsedFeed, parse_feed_with_base};
use music_dht::podcast::{FeedUrl, PodcastId};
use super::fetch::{FeedBody, Fetcher, HttpStatusError, Validators};
use super::{OpLog, blocking};
/// A successfully checked feed is checked again after this long.
pub const REFRESH_INTERVAL: Duration = Duration::from_secs(60 * 60);
/// First retry after a failed check; doubles per consecutive failure.
pub const FAILURE_BACKOFF_BASE: Duration = Duration::from_secs(5 * 60);
/// Longest wait between checks of a failing feed (also caps `Retry-After`).
pub const FAILURE_BACKOFF_MAX: Duration = Duration::from_secs(24 * 60 * 60);
/// Store, HTTP client and sync log shared by podcast background tasks.
#[derive(Clone)]
pub struct Services {
pub store: Arc<PodcastStore>,
pub fetcher: Arc<Fetcher>,
pub log: Arc<dyn OpLog>,
/// Device-local privacy confirmations for sharing (never synced).
pub confirmations: Arc<super::publication::ShareConfirmations>,
}
impl std::fmt::Debug for Services {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Services")
.field("store", &self.store)
.finish_non_exhaustive()
}
}
/// Result of [`subscribe`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SubscribeReport {
pub podcast_id: PodcastId,
pub title: String,
/// The podcast was already subscribed; nothing was fetched or written.
pub already_subscribed: bool,
/// Episodes the first refresh added to the catalog.
pub new_episodes: usize,
}
/// Result of [`refresh`].
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct RefreshReport {
/// The server answered 304 Not Modified.
pub not_modified: bool,
pub new_episodes: usize,
pub updated_episodes: usize,
/// Feed items without identity or with invalid metadata.
pub skipped_items: usize,
/// New fetch URL after a permanent redirect or `itunes:new-feed-url`.
pub moved_to: Option<FeedUrl>,
}
/// When to check a feed again after a success.
pub fn next_check_after_success(now_ms: i64) -> i64 {
now_ms.saturating_add(duration_ms(REFRESH_INTERVAL))
}
/// When to check a feed again after its `failures`-th consecutive failure:
/// exponential back-off, at least the server's `Retry-After`, at most
/// [`FAILURE_BACKOFF_MAX`].
pub fn next_check_after_failure(now_ms: i64, failures: u32, retry_after: Option<Duration>) -> i64 {
let exponent = failures.saturating_sub(1).min(16);
let backoff = FAILURE_BACKOFF_BASE
.saturating_mul(1 << exponent)
.max(retry_after.unwrap_or_default())
.min(FAILURE_BACKOFF_MAX);
now_ms.saturating_add(duration_ms(backoff))
}
fn duration_ms(duration: Duration) -> i64 {
i64::try_from(duration.as_millis()).unwrap_or(i64::MAX)
}
/// Subscribes to the feed the user typed (`FeedUrl::from_user_input`).
///
/// Nothing is stored unless the URL serves a parsable feed. A URL that
/// resolves (directly or through a known alias or redirect) to a podcast
/// this device already knows reuses its id, so resubscribing continues the
/// saved progress and history. The subscription is private.
pub async fn subscribe(services: &Services, input: &str, now_ms: i64) -> Result<SubscribeReport> {
let url = FeedUrl::from_user_input(input).map_err(|err| anyhow!("{err}"))?;
subscribe_url(services, url, now_ms).await
}
/// Subscribes to `url` exactly as given (see [`subscribe`]).
///
/// Subscribing from a public card passes the card's origin URL here
/// (`podcasts::discovery::subscribe_from_hit`): the id then matches the
/// card's `podcast_id` unless this device already knows the URL as an alias
/// of another podcast, and everything stored comes from the feed itself.
pub async fn subscribe_url(
services: &Services,
url: FeedUrl,
now_ms: i64,
) -> Result<SubscribeReport> {
if let Some(report) = already_subscribed(services, &url).await? {
return Ok(report);
}
let response = services
.fetcher
.fetch_feed(&url, Validators::default())
.await?;
let FeedBody::Modified {
body,
etag,
last_modified,
} = response.body
else {
bail!("the server answered 304 Not Modified to an unconditional request");
};
let final_url = response.final_url;
let feed = parse(body, &final_url).await?;
// The feed's own address: where its permanent redirects lead.
let moved_permanently = response.moved_permanently_to.is_some();
let landed = response.moved_permanently_to.unwrap_or(final_url);
// An older address of a feed this device follows under the newer one it
// announces (`itunes:new-feed-url`, no redirect): the same podcast, not
// a second subscription. Nothing is written.
if let Some(announced) = feed
.new_feed_url
.as_deref()
.and_then(|announced| FeedUrl::parse(announced).ok())
.filter(|announced| *announced != url && *announced != landed)
&& let Some(report) = already_subscribed(services, &announced).await?
{
return Ok(report);
}
let store = Arc::clone(&services.store);
let log = Arc::clone(&services.log);
let image_url = feed.image_url.clone();
let report = blocking(move || {
// Identity comes from the URL of the first subscription. Reuse a
// podcast this device already knows under the typed or the final
// URL; otherwise the typed URL defines the id and a permanent
// redirect becomes an alias below.
let identity_url = if knows(&store, &url)? || !knows(&store, &landed)? {
url.clone()
} else {
landed.clone()
};
let meta = feed.to_podcast_meta(identity_url);
let mut subscribed = None;
log.record(&mut |stamps| {
let outcome = store.subscribe(stamps, &meta)?;
let ops = outcome.ops.clone();
subscribed = Some(outcome);
Ok(ops)
})?;
let outcome = subscribed.ok_or_else(|| anyhow!("subscription was not recorded"))?;
let podcast_id = outcome.podcast_id;
let mut refreshed = None;
log.record(&mut |stamps| {
let outcome = store.apply_feed(
stamps,
&FeedRefresh {
podcast_id: &podcast_id,
feed: &feed,
fetched_from: &landed,
moved_permanently,
},
)?;
let ops = outcome.ops.clone();
refreshed = Some(outcome);
Ok(ops)
})?;
let refreshed = refreshed.ok_or_else(|| anyhow!("feed refresh was not recorded"))?;
store.record_fetch_success(
&podcast_id,
now_ms,
etag.as_deref(),
last_modified.as_deref(),
Some(next_check_after_success(now_ms)),
)?;
Ok(SubscribeReport {
podcast_id,
title: meta.title,
already_subscribed: outcome.already_subscribed,
new_episodes: refreshed.new_episodes,
})
})
.await?;
if let Some(image_url) = image_url {
update_cover(services, &report.podcast_id, &image_url).await;
}
Ok(report)
}
/// The subscription `url` belongs to on this device (directly or as a
/// known feed alias), as an "already subscribed" report.
async fn already_subscribed(services: &Services, url: &FeedUrl) -> Result<Option<SubscribeReport>> {
let store = Arc::clone(&services.store);
let lookup = url.clone();
blocking(move || {
let Some(podcast_id) = subscribed_podcast(&store, &lookup)? else {
return Ok(None);
};
let title = store
.podcast(&podcast_id)?
.map(|summary| summary.meta.title);
Ok(Some(SubscribeReport {
podcast_id,
title: title.unwrap_or_default(),
already_subscribed: true,
new_episodes: 0,
}))
})
.await
}
/// The podcast `url` resolves to on this device (feed aliases included),
/// when it is subscribed. Blocking.
pub(crate) fn subscribed_podcast(store: &PodcastStore, url: &FeedUrl) -> Result<Option<PodcastId>> {
let id = store.resolve_podcast_id(url)?;
let subscribed = store
.subscription(&id)?
.is_some_and(|record| record.subscribed);
Ok(subscribed.then_some(id))
}
fn knows(store: &PodcastStore, url: &FeedUrl) -> Result<bool> {
let id = store.resolve_podcast_id(url)?;
Ok(store.podcast(&id)?.is_some() || store.subscription(&id)?.is_some())
}
/// Checks one feed (conditional GET from `url`, the store's fetch URL) and
/// ingests a changed document. Failures are recorded in the fetch state
/// with back-off and returned; the stored catalog is kept.
pub async fn refresh(
services: &Services,
podcast_id: &PodcastId,
url: &FeedUrl,
now_ms: i64,
) -> Result<RefreshReport> {
let store = Arc::clone(&services.store);
let id = podcast_id.clone();
let fetch_state = blocking(move || store.fetch_state(&id)).await?;
let result = fetch_and_apply(services, podcast_id, url, &fetch_state, now_ms).await;
if let Err(err) = &result {
let message = format!("{err:#}");
let retry_after = err
.downcast_ref::<HttpStatusError>()
.and_then(|status| status.retry_after);
let next = next_check_after_failure(
now_ms,
fetch_state.consecutive_failures.saturating_add(1),
retry_after,
);
let store = Arc::clone(&services.store);
let id = podcast_id.clone();
if let Err(record_err) = blocking(move || {
store
.record_fetch_failure(&id, now_ms, &message, Some(next))
.map(|_| ())
})
.await
{
tracing::warn!("recording a podcast refresh error failed: {record_err:#}");
}
}
result
}
async fn fetch_and_apply(
services: &Services,
podcast_id: &PodcastId,
url: &FeedUrl,
fetch_state: &furumi_library::podcasts::FetchState,
now_ms: i64,
) -> Result<RefreshReport> {
let response = services
.fetcher
.fetch_feed(
url,
Validators {
etag: fetch_state.etag.as_deref(),
last_modified: fetch_state.last_modified.as_deref(),
},
)
.await?;
tracing::debug!(
podcast = %podcast_id,
redirects = response.redirects,
moved_permanently = response.moved_permanently_to.is_some(),
not_modified = matches!(response.body, FeedBody::NotModified),
"podcast feed checked"
);
let next = Some(next_check_after_success(now_ms));
let (body, etag, last_modified) = match response.body {
FeedBody::NotModified => {
let store = Arc::clone(&services.store);
let id = podcast_id.clone();
blocking(move || store.record_fetch_not_modified(&id, now_ms, next)).await?;
return Ok(RefreshReport {
not_modified: true,
..RefreshReport::default()
});
}
FeedBody::Modified {
body,
etag,
last_modified,
} => (body, etag, last_modified),
};
let final_url = response.final_url;
let feed = parse(body, &final_url).await?;
let moved_permanently = response.moved_permanently_to.is_some();
let landed = response.moved_permanently_to.unwrap_or(final_url);
let image_url = feed.image_url.clone();
let store = Arc::clone(&services.store);
let log = Arc::clone(&services.log);
let id = podcast_id.clone();
let previous_url = url.clone();
let report = blocking(move || {
let mut refreshed = None;
log.record(&mut |stamps| {
let outcome = store.apply_feed(
stamps,
// `fetched_from` is the address the permanent redirects led
// to; the document itself may come from a temporary hop
// behind it (parsed against that URL above).
&FeedRefresh {
podcast_id: &id,
feed: &feed,
fetched_from: &landed,
moved_permanently,
},
)?;
let ops = outcome.ops.clone();
refreshed = Some(outcome);
Ok(ops)
})?;
let outcome = refreshed.ok_or_else(|| anyhow!("feed refresh was not recorded"))?;
store.record_fetch_success(&id, now_ms, etag.as_deref(), last_modified.as_deref(), next)?;
Ok(RefreshReport {
not_modified: false,
new_episodes: outcome.new_episodes,
updated_episodes: outcome.updated_episodes,
skipped_items: outcome.skipped_items,
moved_to: outcome
.feed_url
.filter(|feed_url| *feed_url != previous_url),
})
})
.await?;
if let Some(image_url) = image_url {
update_cover(services, podcast_id, &image_url).await;
}
Ok(report)
}
/// Parses a feed document on the blocking pool; relative URLs resolve
/// against where the document was served from.
pub(crate) async fn parse(body: Vec<u8>, base: &FeedUrl) -> Result<ParsedFeed> {
let base = base.as_str().to_string();
blocking(move || {
parse_feed_with_base(&body, Some(&base)).map_err(|err| anyhow!("unusable feed: {err}"))
})
.await
}
/// Downloads the cover when the feed image changed or the cached file is
/// gone, records it and deletes the replaced file. Best effort: failures are
/// only logged, covers are a replaceable cache.
async fn update_cover(services: &Services, podcast_id: &PodcastId, image_url: &str) {
let store = Arc::clone(&services.store);
let id = podcast_id.clone();
let current = blocking(move || {
let state = store.fetch_state(&id)?;
Ok((state.cover_url, state.cover_path))
})
.await;
let (old_url, old_path) = match current {
Ok(current) => current,
Err(err) => {
tracing::warn!("reading podcast cover state failed: {err:#}");
return;
}
};
let cached = old_path
.as_deref()
.is_some_and(|path| Path::new(path).is_file());
if old_url.as_deref() == Some(image_url) && cached {
return;
}
let path = match services.fetcher.fetch_cover(podcast_id, image_url).await {
Ok(path) => path,
Err(err) => {
tracing::debug!(podcast = %podcast_id, "podcast cover download failed: {err:#}");
return;
}
};
let store = Arc::clone(&services.store);
let id = podcast_id.clone();
let image_url = image_url.to_string();
let result = blocking(move || {
let new_path = std::path::absolute(&path)
.unwrap_or(path)
.to_string_lossy()
.into_owned();
store
.set_cover_cache(&id, Some(&image_url), Some(&new_path))
.context("recording the cover")?;
if let Some(old_path) = old_path.filter(|old| *old != new_path) {
let _ = std::fs::remove_file(old_path);
}
Ok(())
})
.await;
if let Err(err) = result {
tracing::warn!("recording a podcast cover failed: {err:#}");
}
}
+971
View File
@@ -0,0 +1,971 @@
//! Seekable playback of a remote episode without downloading it first.
//!
//! Audio is never stored: the reader keeps a bounded in-memory window and
//! the episode stays on the publisher's server (it is not imported, hashed
//! or offered to peers).
//!
//! [`open`] issues one `Range: bytes=0-` request and hands the response to a
//! dedicated downloader thread. The thread fills a bounded in-memory window
//! around the reader position:
//!
//! * up to [`READ_AHEAD`] bytes ahead of the reader (then it pauses),
//! * up to [`KEEP_BEHIND`] bytes behind it (cheap small backward seeks),
//! * plus the first [`HEAD_KEEP`] bytes of the file, kept permanently because
//! decoders re-read the container header while probing.
//!
//! The window buffer is allocated once at its maximum size and never grows,
//! so memory stays bounded (and no large reallocation happens under the lock
//! the audio callback reads through).
//!
//! A seek inside the window is free. A read outside it restarts the
//! downloader at the new position with a fresh `Range` request; a generation
//! counter makes sure bytes from the superseded response are dropped. Servers
//! that ignore `Range` are still supported: forward seeks read and discard,
//! backward seeks restart from the beginning.
//!
//! Network errors: the downloader never gives up on a transient error by
//! itself. It resumes from its current offset with capped exponential backoff
//! (shortened while the reader is waiting for data), so a short outage is
//! bridged by the buffered window. The decision to fail belongs to the
//! reader: a `read` that is blocked on missing data and sees no download
//! progress for [`STARVE_TIMEOUT`] returns `io::ErrorKind::TimedOut`; the next
//! `read` starts a fresh attempt. Client errors (HTTP 4xx other than 408/429,
//! e.g. an expired signed URL) are reported to the reader immediately.
//!
//! Timeouts: `reqwest::blocking` applies `ClientBuilder::timeout` to waiting
//! for the response head and then *separately to every `Response::read`
//! call* (verified in reqwest 0.12.28: `blocking::Response::read` wraps each
//! read in `wait::timeout(.., self.timeout)`, and the blocking client does not
//! forward that value to the async client's total timeout). So
//! `timeout(STALL_TIMEOUT)` is a per-read stall timeout, not a cap on the whole
//! body, and long episodes are fine. The request-level
//! `RequestBuilder::timeout` (which *is* a total timeout) is never used.
//!
//! Cancellation: a stream belongs to one playback start ([`CancelToken`]).
//! Once that start is superseded (another item, stop, restart), every read,
//! including one blocked waiting for data inside the audio callback, fails
//! within [`CANCEL_POLL`], and the downloader thread stops. So a stalled
//! stream never holds the audio thread past the user's next choice, and a
//! superseded resume (which may be reading and discarding up to its offset)
//! stops downloading.
//!
//! End of playback: [`StreamProbe::end`] tells whether the reader saw the
//! file end the way the server described it or stopped on an error, so an
//! episode whose connection was lost is not taken as played to the end.
//!
//! Decoder note for the player integration: symphonia's MP3 demuxer in
//! accurate seek mode never seeks by byte offset (a backward seek re-parses
//! from the first frame), which would re-download the episode. Build rodio
//! decoders for these streams with `.with_coarse_seek(true)` (and
//! `.with_byte_len(..)`), so a seek maps to a single range request.
use std::collections::VecDeque;
use std::io::{self, Read, Seek, SeekFrom};
use std::sync::{Arc, Condvar, Mutex, MutexGuard, PoisonError};
use std::time::{Duration, Instant};
use anyhow::{Context, Result, anyhow, bail};
use reqwest::blocking::{Client, Response};
use reqwest::header::{CONTENT_RANGE, CONTENT_TYPE, RANGE};
use reqwest::{StatusCode, Url};
use super::fetch::redact;
/// Maximum bytes buffered ahead of the reader position.
pub const READ_AHEAD: u64 = 8 * 1024 * 1024;
/// Bytes kept behind the reader position for small backward seeks.
pub const KEEP_BEHIND: u64 = 1024 * 1024;
/// Leading bytes of the file kept for the lifetime of the stream.
pub const HEAD_KEEP: usize = 256 * 1024;
/// Size of a single network read.
const CHUNK: usize = 64 * 1024;
/// Largest the window can get: the read-ahead may overshoot by less than one
/// chunk before the downloader pauses.
const WINDOW_CAP: usize = READ_AHEAD as usize + KEEP_BEHIND as usize + CHUNK;
/// A forward gap up to this size is bridged by waiting for the downloader
/// instead of issuing a new range request.
const NEAR_GAP: u64 = 512 * 1024;
/// A restart this close ahead of the current response offset keeps the
/// response and discards bytes instead of reconnecting.
const DISCARD_LIMIT: u64 = 256 * 1024;
const CONNECT_TIMEOUT: Duration = Duration::from_secs(15);
/// No progress for this long on one read (or the response head) is an error.
const STALL_TIMEOUT: Duration = Duration::from_secs(30);
/// First retry delay; doubles per consecutive failure.
const RETRY_BASE: Duration = Duration::from_millis(250);
/// Longest delay between attempts while the reader still has buffered data.
const MAX_BACKOFF: Duration = Duration::from_secs(10);
/// Longest delay between attempts while the reader is waiting for data.
const STARVED_BACKOFF: Duration = Duration::from_secs(1);
/// A `read` blocked on missing data fails after this long without any
/// download progress. Shorter in tests to keep failure tests fast.
#[cfg(not(test))]
pub const STARVE_TIMEOUT: Duration = Duration::from_secs(30);
#[cfg(test)]
pub const STARVE_TIMEOUT: Duration = Duration::from_secs(4);
/// How often a blocked read or an idle downloader checks its
/// [`CancelToken`].
pub const CANCEL_POLL: Duration = Duration::from_millis(100);
/// Tells a stream that the playback start it belongs to was superseded.
#[derive(Clone)]
pub struct CancelToken(Option<Arc<dyn Fn() -> bool + Send + Sync>>);
impl CancelToken {
/// A stream that is only closed by dropping it.
#[cfg(test)]
pub fn never() -> CancelToken {
CancelToken(None)
}
/// `cancelled` becomes true once the start is superseded; it is polled.
pub fn new(cancelled: impl Fn() -> bool + Send + Sync + 'static) -> CancelToken {
CancelToken(Some(Arc::new(cancelled)))
}
pub fn is_cancelled(&self) -> bool {
self.0.as_ref().is_some_and(|cancelled| cancelled())
}
}
/// The playback start was superseded while the stream was opened or read.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Cancelled;
impl std::fmt::Display for Cancelled {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str("the episode start was superseded")
}
}
impl std::error::Error for Cancelled {}
fn cancelled_error() -> io::Error {
io::Error::other(Cancelled)
}
/// How the reader's last read ended, for telling a finished episode from a
/// lost connection.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StreamEnd {
/// No read failed and the server announced the file size, so the
/// decoder ended at the end the server described.
Complete,
/// No read failed, but the server sent no size: a connection closed
/// early looks exactly like the end of the file.
Unknown,
/// The last read failed (outage longer than [`STARVE_TIMEOUT`], a client
/// error such as an expired URL, or cancellation).
Failed,
}
/// Read-only view of a stream's state that outlives handing the reader to
/// the decoder.
#[derive(Clone)]
pub struct StreamProbe(Arc<Shared>);
impl std::fmt::Debug for StreamProbe {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_tuple("StreamProbe").field(&self.end()).finish()
}
}
impl StreamProbe {
pub fn end(&self) -> StreamEnd {
let state = self.0.lock();
if state.read_failed {
StreamEnd::Failed
} else if state.declared_total {
StreamEnd::Complete
} else {
StreamEnd::Unknown
}
}
}
pub struct OpenedStream {
pub reader: HttpStream,
pub probe: StreamProbe,
pub byte_len: Option<u64>,
pub mime_type: Option<String>,
pub seekable: bool,
}
/// `Read + Seek` view of a remote file; see the module docs.
pub struct HttpStream {
pos: u64,
shared: Arc<Shared>,
}
struct Shared {
state: Mutex<State>,
cancel: CancelToken,
/// Signalled when data, EOF, an error or downloader exit is available to
/// the reader.
data_ready: Condvar,
/// Signalled when the reader moved, requested a restart, started waiting
/// or went away.
space_ready: Condvar,
}
struct State {
/// Bumped on every restart; downloader output for older generations is
/// discarded.
generation: u64,
/// Start offset requested for the current generation.
target: u64,
/// File offset of `window[0]`.
window_start: u64,
window: VecDeque<u8>,
/// Bytes `0..head.len()` of the file.
head: Vec<u8>,
/// Last position the reader consumed from the window.
reader_pos: u64,
total: Option<u64>,
/// `total` comes from the server (`Content-Length` / `Content-Range`),
/// not from a connection that closed.
declared_total: bool,
/// The reader's last read returned an error (cleared by data).
read_failed: bool,
ranges: bool,
/// The current generation reached the end of the body.
done: bool,
/// The current generation was abandoned (fatal error, or the reader gave
/// up waiting); the downloader idles until the reader restarts it.
failed: bool,
/// Fatal error to report to the reader once.
error: Option<(io::ErrorKind, String)>,
/// Most recent transient failure, for the reader's timeout message.
last_error: Option<String>,
/// Bytes received from the network for the current generation
/// (including discarded ones); the reader's stall detection watches it.
progress: u64,
/// The reader is blocked waiting for data.
reader_waiting: bool,
/// The reader went away.
closed: bool,
/// The downloader thread exited.
exited: bool,
peak_buffered: usize,
peak_capacity: usize,
}
impl State {
fn window_end(&self) -> u64 {
self.window_start + self.window.len() as u64
}
fn buffered(&self) -> usize {
self.window.len() + self.head.len()
}
fn restart_at(&mut self, pos: u64) {
self.generation = self.generation.wrapping_add(1);
self.target = pos;
self.window_start = pos;
// Keeps the allocation: the window never needs more than WINDOW_CAP.
self.window.clear();
self.done = false;
self.failed = false;
self.error = None;
self.last_error = None;
self.progress = 0;
}
fn trim_behind(&mut self) {
let keep_from = self.reader_pos.saturating_sub(KEEP_BEHIND);
if keep_from > self.window_start {
let drop = (keep_from - self.window_start).min(self.window.len() as u64) as usize;
self.window.drain(..drop);
self.window_start += drop as u64;
}
}
}
impl Shared {
fn lock(&self) -> MutexGuard<'_, State> {
self.state.lock().unwrap_or_else(PoisonError::into_inner)
}
}
/// [`open_with`] without cancellation.
#[cfg(test)]
pub fn open(url: &str) -> Result<OpenedStream> {
open_with(url, CancelToken::never())
}
/// Opens a remote audio file for streaming playback. Blocking: call it from
/// `spawn_blocking` or a plain thread, never directly on a Tokio worker.
///
/// Only http(s) URLs are accepted. Errors never contain the URL's query,
/// which may hold a private token. Fails with [`Cancelled`] when `cancel`
/// fires before the stream is ready.
pub fn open_with(url: &str, cancel: CancelToken) -> Result<OpenedStream> {
let parsed = Url::parse(url).context("the episode audio URL is invalid")?;
if !matches!(parsed.scheme(), "http" | "https") {
bail!("unsupported audio URL scheme {:?}", parsed.scheme());
}
let shown = redact(&parsed);
let _ = rustls::crypto::ring::default_provider().install_default();
let client = Client::builder()
.connect_timeout(CONNECT_TIMEOUT)
// Per-read stall timeout, see the module docs.
.timeout(STALL_TIMEOUT)
.redirect(reqwest::redirect::Policy::custom(|attempt| {
if attempt.previous().len() >= 10 {
attempt.error("too many redirects")
} else if matches!(attempt.url().scheme(), "http" | "https") {
attempt.follow()
} else {
attempt.stop()
}
}))
.user_agent(concat!(
"furumi/",
env!("CARGO_PKG_VERSION"),
" (podcast reader)"
))
.build()
.context("building the streaming HTTP client")?;
let response = client
.get(parsed)
.header(RANGE, "bytes=0-")
.send()
.map_err(|err| anyhow!(err.without_url()))
.with_context(|| format!("requesting {shown}"))?;
if cancel.is_cancelled() {
return Err(Cancelled.into());
}
let opened = classify(&response, 0).with_context(|| format!("requesting {shown}"))?;
let mime_type = response
.headers()
.get(CONTENT_TYPE)
.and_then(|value| value.to_str().ok())
.and_then(|value| value.split(';').next())
.map(|value| value.trim().to_ascii_lowercase())
.filter(|value| !value.is_empty());
let window = VecDeque::with_capacity(WINDOW_CAP);
let peak_capacity = window.capacity();
let shared = Arc::new(Shared {
state: Mutex::new(State {
generation: 0,
target: 0,
window_start: 0,
window,
head: Vec::with_capacity(HEAD_KEEP),
reader_pos: 0,
total: opened.total,
declared_total: opened.total.is_some(),
read_failed: false,
ranges: opened.ranges,
done: false,
failed: false,
error: None,
last_error: None,
progress: 0,
reader_waiting: false,
closed: false,
exited: false,
peak_buffered: 0,
peak_capacity,
}),
cancel,
data_ready: Condvar::new(),
space_ready: Condvar::new(),
});
// Requests continue at the final URL of the redirect chain.
let downloader = Downloader {
shared: Arc::clone(&shared),
client,
url: response.url().clone(),
};
std::thread::Builder::new()
.name("podcast-stream".to_string())
.spawn(move || downloader.run(response))
.context("spawning the podcast stream thread")?;
Ok(OpenedStream {
probe: StreamProbe(Arc::clone(&shared)),
reader: HttpStream { pos: 0, shared },
byte_len: opened.total,
mime_type,
seekable: opened.total.is_some(),
})
}
struct Classified {
/// Offset of the first body byte.
start: u64,
total: Option<u64>,
ranges: bool,
}
/// Interprets a response to `Range: bytes=<requested>-` (or a plain GET).
fn classify(response: &Response, requested: u64) -> Result<Classified> {
let status = response.status();
if status == StatusCode::PARTIAL_CONTENT {
let range = response
.headers()
.get(CONTENT_RANGE)
.and_then(|value| value.to_str().ok())
.and_then(parse_content_range);
let Some((start, total)) = range else {
bail!("HTTP 206 without a usable Content-Range");
};
if start != requested {
bail!("server returned range starting at {start}, expected {requested}");
}
return Ok(Classified {
start,
total,
ranges: true,
});
}
if status.is_success() {
return Ok(Classified {
start: 0,
total: response.content_length(),
ranges: false,
});
}
Err(StreamStatusError(status.as_u16()).into())
}
/// The audio server answered with an error status.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct StreamStatusError(pub u16);
impl StreamStatusError {
/// The URL itself is wrong or expired (4xx other than 408/429): the
/// feed may know a newer address for the episode.
pub fn url_is_stale(self) -> bool {
(400..500).contains(&self.0) && self.0 != 408 && self.0 != 429
}
}
impl std::fmt::Display for StreamStatusError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match StatusCode::from_u16(self.0) {
Ok(status) => write!(f, "HTTP {status}"),
Err(_) => write!(f, "HTTP {}", self.0),
}
}
}
impl std::error::Error for StreamStatusError {}
/// Parses `bytes <start>-<end>/<total|*>` into `(start, total)`.
fn parse_content_range(value: &str) -> Option<(u64, Option<u64>)> {
let value = value.trim();
let rest = value
.get(..6)
.filter(|unit| unit.eq_ignore_ascii_case("bytes "))
.map(|_| &value[6..])?;
let (range, total) = rest.split_once('/')?;
let (start, _end) = range.trim().split_once('-')?;
let start = start.trim().parse().ok()?;
let total = match total.trim() {
"*" => None,
total => Some(total.parse().ok()?),
};
Some((start, total))
}
/// Why a (re)connection attempt failed.
enum Failure {
/// Worth retrying (network error, 5xx, 408/429, odd range answer).
Transient(String),
/// Retrying will not help (4xx such as 403/404/410).
Fatal(String),
}
struct Downloader {
shared: Arc<Shared>,
client: Client,
url: Url,
}
/// Marks the downloader as exited however `run` returns (including a panic).
struct ExitFlag(Arc<Shared>);
impl Drop for ExitFlag {
fn drop(&mut self) {
// Set under the lock so a reader that checked `exited` and is about
// to wait cannot miss the notification.
let mut state = self.0.lock();
state.exited = true;
drop(state);
self.0.data_ready.notify_all();
}
}
impl Downloader {
fn run(self, first: Response) {
let _exit = ExitFlag(Arc::clone(&self.shared));
let mut generation = 0u64;
let mut response = Some(first);
// File offset of the next byte `response` yields, or where the next
// request should start when there is no response.
let mut offset = 0u64;
// Consecutive failures of the current generation (drives backoff).
let mut failures = 0u32;
let mut buf = vec![0u8; CHUNK];
loop {
if !self.wait_for_work(&mut generation, &mut response, &mut offset, &mut failures) {
return;
}
if response.is_none() {
match self.reopen(offset) {
Ok(Some((next, start))) => {
response = Some(next);
offset = start;
}
Ok(None) => {
// Nothing left at this offset (HTTP 416).
self.mark_done(generation, offset, false);
continue;
}
Err(Failure::Fatal(message)) => {
failures = 0;
self.fail(generation, message);
continue;
}
Err(Failure::Transient(message)) => {
if !self.retry(generation, &mut failures, &message) {
return;
}
continue;
}
}
}
let Some(body) = response.as_mut() else {
continue;
};
let read = body.read(&mut buf);
if self.shared.cancel.is_cancelled() {
return;
}
match read {
Ok(0) => {
response = None;
let total = self.shared.lock().total;
if total.is_some_and(|total| offset < total) {
// Connection closed early: resume from `offset`.
let message = format!("connection closed at byte {offset}");
if !self.retry(generation, &mut failures, &message) {
return;
}
continue;
}
self.mark_done(generation, offset, true);
}
Ok(read) => {
failures = 0;
let start = offset;
offset += read as u64;
self.publish(generation, start, &buf[..read]);
}
Err(err) if err.kind() == io::ErrorKind::Interrupted => {}
Err(err) => {
response = None;
if !self.retry(generation, &mut failures, &err.to_string()) {
return;
}
}
}
}
}
/// Blocks until there is something to download, adopting restarts
/// requested by the reader. Returns `false` when the reader is gone.
fn wait_for_work(
&self,
generation: &mut u64,
response: &mut Option<Response>,
offset: &mut u64,
failures: &mut u32,
) -> bool {
let mut state = self.shared.lock();
loop {
if state.closed || self.shared.cancel.is_cancelled() {
return false;
}
if state.generation != *generation {
*generation = state.generation;
// A new generation gets a fresh backoff.
*failures = 0;
// Keep the open response when the new target is a little
// ahead of it (or anywhere ahead if ranges are unsupported):
// discarding is cheaper than reconnecting.
let keep = response.is_some()
&& state.target >= *offset
&& (!state.ranges || state.target - *offset <= DISCARD_LIMIT);
if !keep {
*response = None;
*offset = state.target;
}
continue;
}
let paused = state.done
|| state.failed
|| state.window_end() >= state.reader_pos.saturating_add(READ_AHEAD);
if !paused {
return true;
}
state = self
.shared
.space_ready
.wait_timeout(state, CANCEL_POLL)
.unwrap_or_else(PoisonError::into_inner)
.0;
}
}
/// Requests the file from `offset` (from 0 when ranges are unsupported).
/// `Ok(None)` means the server has nothing at that offset.
fn reopen(&self, offset: u64) -> std::result::Result<Option<(Response, u64)>, Failure> {
let ranges = self.shared.lock().ranges;
let mut request = self.client.get(self.url.clone());
if ranges {
request = request.header(RANGE, format!("bytes={offset}-"));
}
let response = request
.send()
.map_err(|err| Failure::Transient(format!("{:#}", anyhow!(err.without_url()))))?;
let status = response.status();
if ranges && status == StatusCode::RANGE_NOT_SATISFIABLE {
return Ok(None);
}
if status.is_client_error()
&& status != StatusCode::REQUEST_TIMEOUT
&& status != StatusCode::TOO_MANY_REQUESTS
{
return Err(Failure::Fatal(format!("HTTP {status}")));
}
let classified = classify(&response, if ranges { offset } else { 0 })
.map_err(|err| Failure::Transient(format!("{err:#}")))?;
let mut state = self.shared.lock();
if !classified.ranges && state.ranges {
// The server stopped honouring Range: read from 0 and discard.
state.ranges = false;
}
if state.total.is_none() && classified.total.is_some() {
state.total = classified.total;
state.declared_total = true;
}
Ok(Some((response, classified.start)))
}
fn mark_done(&self, generation: u64, offset: u64, learn_total: bool) {
let mut state = self.shared.lock();
if state.generation != generation {
return;
}
state.done = true;
if learn_total && state.total.is_none() {
state.total = Some(offset.max(state.window_end()));
}
self.shared.data_ready.notify_all();
}
/// Abandons the current generation with an error for the reader.
fn fail(&self, generation: u64, message: String) {
let mut state = self.shared.lock();
if state.generation != generation {
return;
}
tracing::warn!("podcast stream failed: {message}");
state.failed = true;
state.error = Some((io::ErrorKind::Other, message));
self.shared.data_ready.notify_all();
}
/// Records a transient failure and backs off before the next attempt.
/// Returns `false` when the thread should exit.
fn retry(&self, generation: u64, failures: &mut u32, message: &str) -> bool {
let mut state = self.shared.lock();
if state.closed {
return false;
}
if state.generation != generation {
// The reader moved on; `wait_for_work` adopts the new target.
return true;
}
*failures = failures.saturating_add(1);
state.last_error = Some(message.to_string());
tracing::debug!("podcast stream attempt failed ({failures} in a row): {message}");
let delay = RETRY_BASE
.saturating_mul(1 << (*failures - 1).min(6))
.min(MAX_BACKOFF);
let started = Instant::now();
// Wakes early when the reader goes away, seeks elsewhere or starts
// waiting for data (which shortens the delay).
loop {
if state.closed || self.shared.cancel.is_cancelled() {
return false;
}
if state.generation != generation {
return true;
}
let limit = if state.reader_waiting {
delay.min(STARVED_BACKOFF)
} else {
delay
};
let elapsed = started.elapsed();
if elapsed >= limit {
return true;
}
state = self
.shared
.space_ready
.wait_timeout(state, (limit - elapsed).min(CANCEL_POLL))
.unwrap_or_else(PoisonError::into_inner)
.0;
}
}
fn publish(&self, generation: u64, start: u64, bytes: &[u8]) {
let mut state = self.shared.lock();
if state.generation != generation {
return;
}
state.progress = state.progress.wrapping_add(bytes.len() as u64);
state.last_error = None;
let end = start + bytes.len() as u64;
// Permanent copy of the file head for format probing.
let head_len = state.head.len() as u64;
if start <= head_len && end > head_len && head_len < HEAD_KEEP as u64 {
let from = (head_len - start) as usize;
let to = (HEAD_KEEP as u64).min(end) - start;
state.head.extend_from_slice(&bytes[from..to as usize]);
}
// Only bytes at or after the window end are new; earlier ones are
// being skipped (Range-less seek or resume) or are already buffered.
let want = state.window_end();
if end > want {
if start > want {
// A gap should not happen; resynchronise rather than corrupt.
state.window.clear();
state.window_start = start;
state.window.extend(bytes);
} else {
state.window.extend(&bytes[(want - start) as usize..]);
}
state.trim_behind();
}
state.peak_buffered = state.peak_buffered.max(state.buffered());
state.peak_capacity = state.peak_capacity.max(state.window.capacity());
self.shared.data_ready.notify_all();
}
}
fn downloader_stopped() -> io::Error {
io::Error::other("podcast stream downloader stopped")
}
impl Read for HttpStream {
fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
if buf.is_empty() {
return Ok(0);
}
let shared = &*self.shared;
let state = shared.lock();
let (mut state, result) = read_locked(shared, &mut self.pos, state, buf);
state.reader_waiting = false;
match &result {
Ok(0) => {}
Ok(_) => state.read_failed = false,
Err(_) => state.read_failed = true,
}
result
}
}
/// The body of [`HttpStream::read`]; hands the guard back so the caller can
/// clear `reader_waiting` on every exit path.
fn read_locked<'a>(
shared: &Shared,
pos: &mut u64,
mut state: MutexGuard<'a, State>,
buf: &mut [u8],
) -> (MutexGuard<'a, State>, io::Result<usize>) {
// When this read started waiting, and the download progress then.
let mut starved: Option<(Instant, u64)> = None;
loop {
if shared.cancel.is_cancelled() {
return (state, Err(cancelled_error()));
}
if state.total.is_some_and(|total| *pos >= total) {
return (state, Ok(0));
}
if *pos < state.head.len() as u64 {
let from = *pos as usize;
let len = buf.len().min(state.head.len() - from);
buf[..len].copy_from_slice(&state.head[from..from + len]);
*pos += len as u64;
return (state, Ok(len));
}
let window_end = state.window_end();
if *pos >= state.window_start && *pos < window_end {
let from = (*pos - state.window_start) as usize;
let len = buf.len().min(state.window.len() - from);
let (front, back) = state.window.as_slices();
copy_from_ring(front, back, from, &mut buf[..len]);
*pos += len as u64;
state.reader_pos = *pos;
// Free what fell out of the keep-behind range even when the
// downloader is idle (paused or done).
state.trim_behind();
shared.space_ready.notify_all();
return (state, Ok(len));
}
// Not buffered. Wait for the current generation if it is heading
// here, otherwise restart the downloader at the reader position.
let reachable = *pos >= state.window_start
&& (!state.ranges || *pos <= window_end.saturating_add(NEAR_GAP));
if reachable && !state.failed {
if state.done {
return (state, Ok(0));
}
if state.exited {
return (state, Err(downloader_stopped()));
}
if state.reader_pos != *pos {
state.reader_pos = *pos;
state.trim_behind();
shared.space_ready.notify_all();
}
let now = Instant::now();
let since = match starved {
Some((since, seen)) if seen == state.progress => since,
_ => {
starved = Some((now, state.progress));
now
}
};
let waited = now.saturating_duration_since(since);
if waited >= STARVE_TIMEOUT {
// Give up on this generation; the next read retries.
state.failed = true;
state.error = None;
let cause = state
.last_error
.take()
.unwrap_or_else(|| "no data received".to_string());
let error = io::Error::new(
io::ErrorKind::TimedOut,
format!(
"podcast stream stalled for {}s: {cause}",
STARVE_TIMEOUT.as_secs()
),
);
return (state, Err(error));
}
if !state.reader_waiting {
// Lets a downloader in backoff retry sooner.
state.reader_waiting = true;
shared.space_ready.notify_all();
}
state = shared
.data_ready
.wait_timeout(state, (STARVE_TIMEOUT - waited).min(CANCEL_POLL))
.unwrap_or_else(PoisonError::into_inner)
.0;
continue;
}
if let Some((kind, message)) = state.error.take() {
// Report once; the next read retries from scratch.
return (state, Err(io::Error::new(kind, message)));
}
if state.exited {
return (state, Err(downloader_stopped()));
}
state.restart_at(*pos);
state.reader_pos = *pos;
starved = None;
shared.space_ready.notify_all();
}
}
fn copy_from_ring(front: &[u8], back: &[u8], from: usize, out: &mut [u8]) {
let mut written = 0;
if from < front.len() {
let len = out.len().min(front.len() - from);
out[..len].copy_from_slice(&front[from..from + len]);
written = len;
}
if written < out.len() {
let back_from = from + written - front.len();
let len = out.len() - written;
out[written..].copy_from_slice(&back[back_from..back_from + len]);
}
}
impl Seek for HttpStream {
fn seek(&mut self, position: SeekFrom) -> io::Result<u64> {
let target = match position {
SeekFrom::Start(offset) => i128::from(offset),
SeekFrom::Current(delta) => i128::from(self.pos) + i128::from(delta),
SeekFrom::End(delta) => {
let Some(total) = self.shared.lock().total else {
return Err(io::Error::new(
io::ErrorKind::Unsupported,
"stream length is unknown",
));
};
i128::from(total) + i128::from(delta)
}
};
let target = u64::try_from(target).map_err(|_| {
io::Error::new(
io::ErrorKind::InvalidInput,
"invalid seek to a negative or overflowing position",
)
})?;
// Lazy: the downloader is only redirected when a read needs data.
self.pos = target;
Ok(target)
}
}
impl Drop for HttpStream {
fn drop(&mut self) {
let mut state = self.shared.lock();
state.closed = true;
state.window = VecDeque::new();
state.head = Vec::new();
drop(state);
self.shared.space_ready.notify_all();
self.shared.data_ready.notify_all();
}
}
#[cfg(test)]
impl HttpStream {
/// Bytes currently held in memory (window + head).
pub(super) fn buffered_bytes(&self) -> usize {
self.shared.lock().buffered()
}
/// Highest number of bytes ever held in memory at once.
pub(super) fn peak_buffered_bytes(&self) -> usize {
self.shared.lock().peak_buffered
}
/// Largest allocation (window + head capacity) ever held.
pub(super) fn peak_allocated_bytes(&self) -> usize {
let state = self.shared.lock();
state.peak_capacity + state.head.capacity()
}
/// Flag the downloader thread sets when it exits.
pub(super) fn exit_probe(&self) -> impl Fn() -> bool + Send + 'static {
let shared = Arc::clone(&self.shared);
move || shared.lock().exited
}
}
/// Upper bound of [`HttpStream`] memory use, for tests.
#[cfg(test)]
pub(super) const MAX_BUFFERED: usize = WINDOW_CAP + HEAD_KEEP;
+405
View File
@@ -0,0 +1,405 @@
//! Tests of the HTTP Range stream reader against the local test server:
//! sequential reads, seeks inside and outside the window, servers without
//! Range or Content-Length, transient cuts, persistent failures, bounded
//! memory and thread shutdown.
use super::stream::{self, MAX_BUFFERED};
use super::test_server::{Route, TestServer, noise};
use std::io::{ErrorKind, Read, Seek, SeekFrom};
use std::time::{Duration, Instant};
const MIB: usize = 1024 * 1024;
fn read_to_end(reader: &mut impl Read) -> Vec<u8> {
let mut out = Vec::new();
reader.read_to_end(&mut out).unwrap();
out
}
fn read_n(reader: &mut impl Read, len: usize) -> Vec<u8> {
let mut out = vec![0; len];
reader.read_exact(&mut out).unwrap();
out
}
fn serve(route: Route) -> (TestServer, String) {
let server = TestServer::start();
server.set("/audio.mp3", route);
let url = server.url("/audio.mp3");
(server, url)
}
#[test]
fn sequential_read_matches_source() {
let body = noise(3 * MIB + 123, 1);
let (server, url) = serve(Route::new(body.clone(), "audio/mpeg; charset=binary"));
let mut opened = stream::open(&url).unwrap();
assert_eq!(opened.byte_len, Some(body.len() as u64));
assert_eq!(opened.mime_type.as_deref(), Some("audio/mpeg"));
assert!(opened.seekable);
assert_eq!(read_to_end(&mut opened.reader), body);
let mut buf = [0u8; 16];
assert_eq!(opened.reader.read(&mut buf).unwrap(), 0, "EOF stays EOF");
assert_eq!(server.ranges("/audio.mp3"), [Some("bytes=0-".to_string())]);
}
#[test]
fn seeks_forward_backward_and_from_end() {
let body = noise(12 * MIB, 2);
let (server, url) = serve(Route::new(body.clone(), "audio/mpeg"));
let mut reader = stream::open(&url).unwrap().reader;
assert_eq!(read_n(&mut reader, 1000), body[..1000]);
// Far forward: outside the read-ahead window -> new range request.
let far = 11 * MIB + 7;
assert_eq!(
reader.seek(SeekFrom::Start(far as u64)).unwrap(),
far as u64
);
assert_eq!(read_n(&mut reader, 70_000), body[far..far + 70_000]);
assert!(
server
.ranges("/audio.mp3")
.contains(&Some(format!("bytes={far}-")))
);
// Small backward seek within the kept window: no new request.
let requests = server.ranges("/audio.mp3").len();
reader.seek(SeekFrom::Current(-50_000)).unwrap();
let pos = far + 20_000;
assert_eq!(read_n(&mut reader, 1000), body[pos..pos + 1000]);
assert_eq!(server.ranges("/audio.mp3").len(), requests);
// Back into the permanently kept head: no new request.
reader.seek(SeekFrom::Start(10)).unwrap();
assert_eq!(read_n(&mut reader, 100), body[10..110]);
assert_eq!(server.ranges("/audio.mp3").len(), requests);
// Backward outside the window and the head.
let back = 2 * MIB + 3;
reader.seek(SeekFrom::Start(back as u64)).unwrap();
assert_eq!(read_n(&mut reader, 300_000), body[back..back + 300_000]);
// From the end.
let end = reader.seek(SeekFrom::End(-100)).unwrap();
assert_eq!(end, body.len() as u64 - 100);
assert_eq!(read_to_end(&mut reader), body[body.len() - 100..]);
// Past the end.
let beyond = reader.seek(SeekFrom::End(50)).unwrap();
assert_eq!(beyond, body.len() as u64 + 50);
let mut buf = [0u8; 8];
assert_eq!(reader.read(&mut buf).unwrap(), 0);
assert_eq!(
reader
.seek(SeekFrom::Current(-(beyond as i64) - 1))
.unwrap_err()
.kind(),
ErrorKind::InvalidInput
);
}
#[test]
fn server_without_range_support() {
let body = noise(3 * MIB, 3);
let (server, url) = serve(Route::new(body.clone(), "audio/mpeg").no_ranges());
let opened = stream::open(&url).unwrap();
assert!(opened.seekable, "length is known");
let mut reader = opened.reader;
assert_eq!(read_n(&mut reader, 400_000), body[..400_000]);
// Forward seek: read and discard on the same response.
reader.seek(SeekFrom::Start(2 * MIB as u64)).unwrap();
assert_eq!(read_n(&mut reader, 1000), body[2 * MIB..2 * MIB + 1000]);
// Backward seek outside window and head: restart from 0.
reader.seek(SeekFrom::Start(300_000)).unwrap();
let _ = read_n(&mut reader, 1);
reader.seek(SeekFrom::Start(300_000)).unwrap();
assert_eq!(read_to_end(&mut reader), body[300_000..]);
let requests = server.ranges("/audio.mp3");
assert!(requests.len() >= 2, "{requests:?}");
assert!(requests[1..].iter().all(Option::is_none), "{requests:?}");
reader.seek(SeekFrom::End(-10)).unwrap();
assert_eq!(read_to_end(&mut reader), body[body.len() - 10..]);
}
#[test]
fn unknown_length_is_not_seekable_from_end() {
let body = noise(MIB + 5, 4);
let (_server, url) = serve(
Route::new(body.clone(), "audio/mpeg")
.no_ranges()
.no_length(),
);
let opened = stream::open(&url).unwrap();
assert!(!opened.seekable);
assert_eq!(opened.byte_len, None);
let mut reader = opened.reader;
assert_eq!(
reader.seek(SeekFrom::End(0)).unwrap_err().kind(),
ErrorKind::Unsupported
);
assert_eq!(read_to_end(&mut reader), body);
}
#[test]
fn transient_disconnects_are_retried() {
let body = noise(2 * MIB, 5);
let (server, url) = serve(Route::new(body.clone(), "audio/mpeg").cut(700_000, 2));
let mut reader = stream::open(&url).unwrap().reader;
assert_eq!(read_to_end(&mut reader), body);
let requests = server.ranges("/audio.mp3");
assert_eq!(requests.len(), 3, "{requests:?}");
assert_eq!(requests[1], Some("bytes=700000-".to_string()));
}
#[test]
fn persistent_failure_surfaces_an_error() {
let body = noise(2 * MIB, 6);
let (_server, url) = serve(Route::new(body, "audio/mpeg").cut(100_000, 100));
let mut reader = stream::open(&url).unwrap().reader;
let mut out = Vec::new();
let started = Instant::now();
let err = reader.read_to_end(&mut out).unwrap_err();
assert_eq!(out.len(), 100_000);
assert_eq!(err.kind(), ErrorKind::TimedOut, "{err}");
assert!(err.to_string().contains("stalled"), "{err}");
// Bounded by the starvation deadline, not by a retry count.
assert!(started.elapsed() >= stream::STARVE_TIMEOUT);
assert!(started.elapsed() < stream::STARVE_TIMEOUT * 3);
}
/// An outage that ends while buffered audio is still playing must not
/// end playback: the downloader keeps retrying instead of giving up
/// after a fixed number of attempts.
#[test]
fn outage_shorter_than_the_buffer_is_bridged() {
let body = noise(3 * MIB, 10);
let (server, url) = serve(Route::new(body.clone(), "audio/mpeg").cut(MIB, 4));
let mut reader = stream::open(&url).unwrap().reader;
assert_eq!(read_n(&mut reader, 1000), body[..1000]);
// "Play" buffered audio while the server fails four times and then
// recovers.
std::thread::sleep(Duration::from_millis(4500));
assert_eq!(read_to_end(&mut reader), body[1000..]);
let requests = server.ranges("/audio.mp3");
assert_eq!(requests.len(), 5, "{requests:?}");
assert!(
requests[1..]
.iter()
.all(|range| range.as_deref() == Some("bytes=1048576-")),
"{requests:?}"
);
}
#[test]
fn client_errors_are_reported_without_waiting() {
let body = noise(2 * MIB, 11);
let (server, url) = serve(Route::new(body, "audio/mpeg").cut(100_000, 1));
let mut reader = stream::open(&url).unwrap().reader;
// The signed URL "expires" after the first response.
server.set("/audio.mp3", Route::new("gone", "text/plain").status(404));
let started = Instant::now();
let mut out = Vec::new();
let err = reader.read_to_end(&mut out).unwrap_err();
assert_eq!(out.len(), 100_000);
assert!(err.to_string().contains("404"), "{err}");
assert!(
started.elapsed() < stream::STARVE_TIMEOUT,
"{:?}",
started.elapsed()
);
}
#[test]
fn large_body_keeps_memory_bounded() {
let body = noise(20 * MIB, 7);
let (_server, url) = serve(Route::new(body.clone(), "audio/mpeg"));
let mut reader = stream::open(&url).unwrap().reader;
let mut buf = vec![0u8; 32 * 1024];
let mut pos = 0usize;
let mut hasher_ok = true;
loop {
let read = reader.read(&mut buf).unwrap();
if read == 0 {
break;
}
hasher_ok &= buf[..read] == body[pos..pos + read];
pos += read;
if pos % (2 * MIB) < 32 * 1024 && pos + stream::READ_AHEAD as usize <= body.len() {
// Let the downloader run ahead until it pauses at its cap.
let deadline = Instant::now() + Duration::from_secs(5);
while reader.buffered_bytes() < stream::READ_AHEAD as usize && Instant::now() < deadline
{
std::thread::sleep(Duration::from_millis(5));
}
}
assert!(reader.buffered_bytes() <= MAX_BUFFERED);
}
assert_eq!(pos, body.len());
assert!(hasher_ok, "data mismatch");
let peak = reader.peak_buffered_bytes();
assert!(peak <= MAX_BUFFERED, "peak {peak} > {MAX_BUFFERED}");
assert!(
peak > 4 * MIB,
"read-ahead should have buffered, peak {peak}"
);
// Far seeks restart the window without growing its allocation.
for target in [MIB + 5, 15 * MIB, 3 * MIB] {
reader.seek(SeekFrom::Start(target as u64)).unwrap();
assert_eq!(read_n(&mut reader, 1000), body[target..target + 1000]);
let deadline = Instant::now() + Duration::from_secs(5);
while reader.buffered_bytes() < stream::READ_AHEAD as usize && Instant::now() < deadline {
std::thread::sleep(Duration::from_millis(5));
}
}
// The allocation, not just the length, is bounded.
let allocated = reader.peak_allocated_bytes();
assert!(
allocated <= MAX_BUFFERED,
"allocated {allocated} > {MAX_BUFFERED}"
);
}
#[test]
fn dropping_the_reader_stops_the_thread() {
let body = noise(20 * MIB, 8);
let (_server, url) = serve(Route::new(body.clone(), "audio/mpeg"));
let mut reader = stream::open(&url).unwrap().reader;
assert_eq!(read_n(&mut reader, 100_000), body[..100_000]);
let exited = reader.exit_probe();
let deadline = Instant::now() + Duration::from_secs(5);
// Let it fill the read-ahead window (it then pauses).
while reader.buffered_bytes() < stream::READ_AHEAD as usize && Instant::now() < deadline {
std::thread::sleep(Duration::from_millis(10));
}
assert!(!exited());
drop(reader);
let deadline = Instant::now() + Duration::from_secs(5);
while !exited() && Instant::now() < deadline {
std::thread::sleep(Duration::from_millis(10));
}
assert!(exited(), "downloader thread did not stop");
// Also while actively downloading (not paused).
let mut reader = stream::open(&url).unwrap().reader;
let exited = reader.exit_probe();
let _ = read_n(&mut reader, 10);
drop(reader);
let deadline = Instant::now() + Duration::from_secs(5);
while !exited() && Instant::now() < deadline {
std::thread::sleep(Duration::from_millis(10));
}
assert!(exited(), "downloader thread did not stop");
}
/// The documented calling convention: `open` on Tokio's blocking pool,
/// reads on another plain thread (like the audio thread).
#[test]
fn open_from_spawn_blocking() {
let body = noise(MIB, 9);
let (server, url) = serve(Route::new(body.clone(), "audio/mpeg"));
server.set("/missing.mp3", Route::new("x", "text/plain").status(404));
let missing = server.url("/missing.mp3");
let runtime = tokio::runtime::Builder::new_multi_thread()
.worker_threads(2)
.enable_all()
.build()
.unwrap();
let (opened, failed) = runtime.block_on(async move {
let opened = tokio::task::spawn_blocking(move || stream::open(&url))
.await
.unwrap();
let failed = tokio::task::spawn_blocking(move || stream::open(&missing).is_err())
.await
.unwrap();
(opened, failed)
});
assert!(failed);
let mut reader = opened.unwrap().reader;
let read = std::thread::spawn(move || read_to_end(&mut reader))
.join()
.unwrap();
assert_eq!(read, body);
drop(runtime);
}
#[test]
fn open_fails_for_http_errors() {
let (_server, url) = serve(Route::new("gone", "text/plain").status(404));
let err = stream::open(&url).err().expect("404 must fail");
assert!(format!("{err:#}").contains("404"), "{err:#}");
}
#[test]
fn errors_do_not_show_the_url_query() {
let server = TestServer::start();
// The test server matches paths with their query, so this is a 404.
let err = stream::open(&server.url("/private.mp3?token=s3cr3t"))
.err()
.expect("404 must fail");
let message = format!("{err:#}");
assert!(message.contains("404"), "{message}");
assert!(!message.contains("s3cr3t"), "{message}");
let err = stream::open("file:///etc/passwd").err().expect("not http");
assert!(format!("{err:#}").contains("scheme"), "{err:#}");
}
#[test]
fn http_stream_is_send_and_sync() {
fn check<T: Send + Sync + std::io::Read + std::io::Seek>() {}
check::<stream::HttpStream>();
}
/// A read blocked on a stalled server (inside the audio callback, in the
/// player) returns as soon as its playback is superseded, instead of after
/// `STARVE_TIMEOUT`, and the downloader stops; the stream then reports a
/// failed end.
#[test]
fn a_blocked_read_fails_as_soon_as_its_playback_is_superseded() {
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
let body = noise(4 * MIB, 10);
let (_server, url) = serve(Route::new(body.clone(), "audio/mpeg").cut(MIB, usize::MAX));
let superseded = Arc::new(AtomicBool::new(false));
let flag = Arc::clone(&superseded);
let opened = stream::open_with(
&url,
stream::CancelToken::new(move || flag.load(Ordering::SeqCst)),
)
.unwrap();
let probe = opened.probe.clone();
let mut reader = opened.reader;
let exited = reader.exit_probe();
assert_eq!(read_n(&mut reader, MIB), body[..MIB]);
assert_eq!(probe.end(), stream::StreamEnd::Complete);
let reading = std::thread::spawn(move || {
let mut buf = [0u8; 1024];
let started = Instant::now();
let result = reader.read(&mut buf);
(result, started.elapsed(), reader)
});
std::thread::sleep(Duration::from_millis(300));
superseded.store(true, Ordering::SeqCst);
let (result, waited, mut reader) = reading.join().unwrap();
let err = result.expect_err("superseded");
assert!(
err.get_ref()
.is_some_and(|inner| inner.is::<stream::Cancelled>()),
"{err}"
);
assert!(
waited < stream::STARVE_TIMEOUT / 2,
"blocked for {waited:?}"
);
assert_eq!(probe.end(), stream::StreamEnd::Failed);
// Later reads fail at once, even from buffered data.
reader.seek(SeekFrom::Start(0)).unwrap();
assert!(reader.read(&mut [0u8; 16]).is_err());
let deadline = Instant::now() + Duration::from_secs(2);
while !exited() && Instant::now() < deadline {
std::thread::sleep(Duration::from_millis(10));
}
assert!(exited(), "downloader thread did not stop");
}
+364
View File
@@ -0,0 +1,364 @@
//! Minimal HTTP/1.1 server on 127.0.0.1 for podcast tests (no internet).
//! One request per connection (`Connection: close`). Besides feeds it serves
//! audio like a publisher: `Range` requests (206 / 416) unless disabled,
//! optionally without `Content-Length`, and connections cut after a number
//! of bytes to simulate outages.
use std::collections::HashMap;
use std::io::{BufRead, BufReader, Write};
use std::net::{TcpListener, TcpStream};
use std::sync::{Arc, Mutex, PoisonError};
use std::time::Duration;
#[derive(Clone)]
pub(super) struct Route {
pub status: u16,
pub body: Arc<Vec<u8>>,
pub content_type: String,
pub etag: Option<String>,
pub last_modified: Option<String>,
/// `Location` of a redirect status.
pub location: Option<String>,
pub retry_after: Option<String>,
/// Honour `Range` requests with 206 responses.
pub ranges: bool,
/// Send `Content-Length` (and the total in `Content-Range`).
pub send_length: bool,
/// Cut the body after this many bytes (absolute file offset)...
pub cut_after: Option<usize>,
/// ...for this many requests; later requests are served in full.
pub fail_times: usize,
/// Wait this long before answering (a hanging server).
pub stall: Option<Duration>,
}
impl Route {
pub fn new(body: impl Into<Vec<u8>>, content_type: &str) -> Route {
Route {
status: 200,
body: Arc::new(body.into()),
content_type: content_type.to_string(),
etag: None,
last_modified: None,
location: None,
retry_after: None,
ranges: true,
send_length: true,
cut_after: None,
fail_times: 0,
stall: None,
}
}
/// Answer only after `delay`.
pub fn stall(mut self, delay: Duration) -> Route {
self.stall = Some(delay);
self
}
/// A server that ignores `Range` and always answers 200 with the file.
pub fn no_ranges(mut self) -> Route {
self.ranges = false;
self
}
/// No `Content-Length`: the client cannot know the file size.
pub fn no_length(mut self) -> Route {
self.send_length = false;
self
}
/// The first `times` responses stop after byte `after`.
pub fn cut(mut self, after: usize, times: usize) -> Route {
self.cut_after = Some(after);
self.fail_times = times;
self
}
pub fn redirect(status: u16, location: &str) -> Route {
Route {
status,
location: Some(location.to_string()),
..Route::new(Vec::new(), "text/plain")
}
}
pub fn status(mut self, status: u16) -> Route {
self.status = status;
self
}
pub fn etag(mut self, etag: &str) -> Route {
self.etag = Some(etag.to_string());
self
}
pub fn last_modified(mut self, value: &str) -> Route {
self.last_modified = Some(value.to_string());
self
}
pub fn retry_after(mut self, value: &str) -> Route {
self.retry_after = Some(value.to_string());
self
}
}
/// Headers of one received request (names lowercased).
pub(super) type RequestHeaders = HashMap<String, String>;
#[derive(Default)]
struct ServerState {
routes: HashMap<String, Route>,
requests: HashMap<String, Vec<RequestHeaders>>,
/// Cut responses served so far, per path.
cuts: HashMap<String, usize>,
}
pub(super) struct TestServer {
base: String,
state: Arc<Mutex<ServerState>>,
}
impl TestServer {
pub fn start() -> TestServer {
let listener = TcpListener::bind("127.0.0.1:0").expect("bind test server");
let base = format!("http://{}", listener.local_addr().expect("local addr"));
let state = Arc::new(Mutex::new(ServerState::default()));
let accept_state = Arc::clone(&state);
std::thread::spawn(move || {
for stream in listener.incoming() {
let Ok(stream) = stream else { continue };
let state = Arc::clone(&accept_state);
std::thread::spawn(move || handle(stream, &state));
}
});
TestServer { base, state }
}
pub fn url(&self, path: &str) -> String {
format!("{}{path}", self.base)
}
pub fn set(&self, path: &str, route: Route) {
self.lock().routes.insert(path.to_string(), route);
}
/// Headers of every request received for `path`, in order.
pub fn requests(&self, path: &str) -> Vec<RequestHeaders> {
self.lock().requests.get(path).cloned().unwrap_or_default()
}
/// The `Range` header of every request for `path` (`None` if absent).
pub fn ranges(&self, path: &str) -> Vec<Option<String>> {
self.requests(path)
.into_iter()
.map(|headers| headers.get("range").cloned())
.collect()
}
fn lock(&self) -> std::sync::MutexGuard<'_, ServerState> {
self.state.lock().unwrap_or_else(PoisonError::into_inner)
}
}
fn handle(stream: TcpStream, state: &Mutex<ServerState>) {
let _ = stream.set_read_timeout(Some(Duration::from_secs(10)));
let mut reader = BufReader::new(match stream.try_clone() {
Ok(stream) => stream,
Err(_) => return,
});
let mut request_line = String::new();
if reader.read_line(&mut request_line).is_err() {
return;
}
let path = request_line
.split_whitespace()
.nth(1)
.unwrap_or("/")
.to_string();
let mut headers = RequestHeaders::new();
loop {
let mut line = String::new();
match reader.read_line(&mut line) {
Ok(0) | Err(_) => return,
Ok(_) => {}
}
let line = line.trim_end();
if line.is_empty() {
break;
}
if let Some((name, value)) = line.split_once(':') {
headers.insert(name.trim().to_ascii_lowercase(), value.trim().to_string());
}
}
let (route, cut) = {
let mut state = state.lock().unwrap_or_else(PoisonError::into_inner);
state
.requests
.entry(path.clone())
.or_default()
.push(headers.clone());
let route = state.routes.get(&path).cloned();
let cut = match &route {
Some(route) if route.cut_after.is_some() => {
let served = state.cuts.entry(path.clone()).or_default();
if *served < route.fail_times {
*served += 1;
route.cut_after
} else {
None
}
}
_ => None,
};
(route, cut)
};
let mut out = stream;
if let Some(delay) = route.as_ref().and_then(|route| route.stall) {
std::thread::sleep(delay);
}
let Some(route) = route else {
let _ = out
.write_all(b"HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\nConnection: close\r\n\r\n");
return;
};
let etag_matches = route
.etag
.as_ref()
.is_some_and(|etag| headers.get("if-none-match") == Some(etag));
let date_matches = route
.last_modified
.as_ref()
.is_some_and(|date| headers.get("if-modified-since") == Some(date));
if route.status == 200 && (etag_matches || date_matches) {
let _ = write!(
out,
"HTTP/1.1 304 Not Modified\r\nConnection: close\r\n\r\n"
);
return;
}
let total = route.body.len();
let mut status = route.status;
let (mut start, mut end) = (0usize, total);
let mut extra = String::new();
if route.status == 200
&& route.ranges
&& let Some(range) = headers
.get("range")
.and_then(|range| range.strip_prefix("bytes="))
&& let Some((from, to)) = range.split_once('-')
&& let Ok(from) = from.trim().parse::<usize>()
{
if from >= total {
let _ = write!(
out,
"HTTP/1.1 416 Range Not Satisfiable\r\nContent-Range: bytes */{total}\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
);
return;
}
status = 206;
start = from;
end = to
.trim()
.parse::<usize>()
.map_or(total, |to| (to + 1).min(total));
let size = if route.send_length {
total.to_string()
} else {
"*".to_string()
};
extra.push_str(&format!(
"Content-Range: bytes {start}-{}/{size}\r\n",
end - 1
));
}
if route.ranges {
extra.push_str("Accept-Ranges: bytes\r\n");
}
if route.send_length {
extra.push_str(&format!("Content-Length: {}\r\n", end - start));
}
for (name, value) in [
("ETag", &route.etag),
("Last-Modified", &route.last_modified),
("Location", &route.location),
("Retry-After", &route.retry_after),
] {
if let Some(value) = value {
extra.push_str(&format!("{name}: {value}\r\n"));
}
}
let reason = match status {
200 => "OK",
206 => "Partial Content",
301 => "Moved Permanently",
302 => "Found",
307 => "Temporary Redirect",
308 => "Permanent Redirect",
404 => "Not Found",
503 => "Service Unavailable",
_ => "Status",
};
if write!(
out,
"HTTP/1.1 {status} {reason}\r\nContent-Type: {}\r\n{extra}Connection: close\r\n\r\n",
route.content_type,
)
.is_err()
{
return;
}
let limit = cut.map_or(end, |cut| cut.clamp(start, end));
for chunk in route.body[start..limit].chunks(64 * 1024) {
if out.write_all(chunk).is_err() {
return;
}
}
let _ = out.flush();
let _ = out.shutdown(std::net::Shutdown::Both);
}
/// Deterministic pseudo-random bytes.
pub(super) fn noise(len: usize, seed: u64) -> Vec<u8> {
let mut state = seed | 1;
let mut out = Vec::with_capacity(len);
while out.len() < len {
state ^= state << 13;
state ^= state >> 7;
state ^= state << 17;
out.extend_from_slice(&state.to_le_bytes());
}
out.truncate(len);
out
}
/// Sample rate of [`wav`].
pub(super) const WAV_RATE: u32 = 8_000;
/// A mono 16-bit PCM WAV file of `seconds` (8 kHz). Every sample of second
/// `n` has the value `n * 40` (up to 13 minutes), so a decoded sample tells where playback
/// is.
pub(super) fn wav(seconds: u32) -> Vec<u8> {
const RATE: u32 = WAV_RATE;
let samples = RATE * seconds;
let data_len = samples * 2;
let mut out = Vec::with_capacity(44 + data_len as usize);
out.extend_from_slice(b"RIFF");
out.extend_from_slice(&(36 + data_len).to_le_bytes());
out.extend_from_slice(b"WAVEfmt ");
out.extend_from_slice(&16u32.to_le_bytes());
out.extend_from_slice(&1u16.to_le_bytes());
out.extend_from_slice(&1u16.to_le_bytes());
out.extend_from_slice(&RATE.to_le_bytes());
out.extend_from_slice(&(RATE * 2).to_le_bytes());
out.extend_from_slice(&2u16.to_le_bytes());
out.extend_from_slice(&16u16.to_le_bytes());
out.extend_from_slice(b"data");
out.extend_from_slice(&data_len.to_le_bytes());
for n in 0..samples {
let second = (n / RATE) as i16;
out.extend_from_slice(&second.saturating_mul(40).to_le_bytes());
}
out
}
+994
View File
@@ -0,0 +1,994 @@
//! Store opening, subscribing and refreshing against a local HTTP server.
//! No internet, no real user directories: every test uses a temp dir.
use std::sync::{Arc, Mutex, PoisonError};
use std::time::Duration;
use anyhow::Result;
use furumi_library::podcasts::{
EpisodeQuery, OpStamp, PodcastListFilter, PodcastLocalOp, PodcastStore, StampSource,
};
use music_dht::device_sync::{SyncOpPayload, SyncOpWire};
use music_dht::podcast::{FeedUrl, PodcastId};
use super::OpLog;
use super::fetch::{FETCH_DEADLINE, MAX_COVER_BYTES, MAX_FEED_BYTES, MAX_REDIRECTS, Validators};
use super::refresh::{
FAILURE_BACKOFF_BASE, FAILURE_BACKOFF_MAX, REFRESH_INTERVAL, Services,
next_check_after_failure, next_check_after_success, refresh, subscribe,
};
use super::test_server::{Route, TestServer};
pub(super) const NOW: i64 = 1_700_000_000_000;
/// In-memory sync log: hands out stamps and keeps the appended operations.
#[derive(Default)]
pub(super) struct MemoryLog {
ops: Mutex<Vec<SyncOpWire>>,
}
struct MemoryStamps {
next_seq: i64,
reserved: Vec<i64>,
}
impl StampSource for MemoryStamps {
fn device_id(&self) -> &str {
"test-device"
}
fn next_stamp(&mut self) -> Result<OpStamp> {
let seq = self.next_seq + self.reserved.len() as i64;
self.reserved.push(seq);
Ok(OpStamp::new(
format!("test-device:{seq}"),
"test-device",
NOW + seq,
))
}
}
impl OpLog for MemoryLog {
fn record(
&self,
action: &mut dyn FnMut(&mut dyn StampSource) -> Result<Vec<PodcastLocalOp>>,
) -> Result<()> {
let mut ops = self.ops.lock().unwrap_or_else(PoisonError::into_inner);
let mut stamps = MemoryStamps {
next_seq: ops.len() as i64 + 1,
reserved: Vec::new(),
};
for (op, seq) in action(&mut stamps)?.into_iter().zip(stamps.reserved) {
ops.push(op.into_wire(seq));
}
Ok(())
}
}
impl MemoryLog {
pub(super) fn kinds(&self) -> Vec<String> {
self.ops
.lock()
.unwrap_or_else(PoisonError::into_inner)
.iter()
.map(|op| {
serde_json::to_value(&op.payload).unwrap()["kind"]
.as_str()
.unwrap()
.to_string()
})
.collect()
}
}
pub(super) struct Fixture {
_dir: tempfile::TempDir,
pub(super) services: Services,
pub(super) log: Arc<MemoryLog>,
pub(super) server: TestServer,
}
pub(super) fn fixture() -> Fixture {
let dir = tempfile::tempdir().unwrap();
let log = Arc::new(MemoryLog::default());
let services = super::open_services(
&dir.path().join("podcasts.sqlite3"),
dir.path().join("covers"),
log.clone(),
)
.unwrap();
Fixture {
_dir: dir,
services,
log,
server: TestServer::start(),
}
}
pub(super) fn rss(items: &[(&str, &str)]) -> Vec<u8> {
let items: String = items
.iter()
.map(|(guid, title)| {
format!(
"<item><title>{title}</title><guid>{guid}</guid>\
<pubDate>Sat, 15 Jun 2024 10:00:00 GMT</pubDate>\
<itunes:duration>45:00</itunes:duration>\
<enclosure url=\"/audio/{guid}.mp3\" type=\"audio/mpeg\" length=\"100\"/></item>"
)
})
.collect();
format!(
"<?xml version=\"1.0\"?><rss version=\"2.0\" \
xmlns:itunes=\"http://www.itunes.com/dtds/podcast-1.0.dtd\"><channel>\
<title>Test Show</title><itunes:author>Host</itunes:author>{items}</channel></rss>"
)
.into_bytes()
}
fn episode_count(store: &PodcastStore, id: &PodcastId) -> usize {
store
.episodes(&EpisodeQuery::new(id.clone()))
.unwrap()
.len()
}
#[tokio::test]
async fn subscribe_then_conditional_refresh_uses_validators() {
let f = fixture();
f.server.set(
"/feed.xml",
Route::new(
rss(&[("a", "Pilot"), ("b", "Second")]),
"application/rss+xml",
)
.etag("\"v1\"")
.last_modified("Sat, 15 Jun 2024 10:00:00 GMT"),
);
let report = subscribe(&f.services, &f.server.url("/feed.xml"), NOW)
.await
.unwrap();
assert!(!report.already_subscribed);
assert_eq!(report.new_episodes, 2);
assert_eq!(report.title, "Test Show");
assert_eq!(f.log.kinds(), ["podcast_subscription_set"]);
let store = &f.services.store;
let rows = store.list_podcasts(PodcastListFilter::Subscribed).unwrap();
assert_eq!(rows.len(), 1);
assert!(!rows[0].shared, "a new subscription is private");
let state = store.fetch_state(&report.podcast_id).unwrap();
assert_eq!(state.etag.as_deref(), Some("\"v1\""));
assert_eq!(state.next_check_at_ms, Some(next_check_after_success(NOW)));
let first = &f.server.requests("/feed.xml")[0];
assert!(!first.contains_key("if-none-match"), "{first:?}");
assert!(
first
.get("user-agent")
.is_some_and(|agent| agent.starts_with("furumi/")),
"{first:?}"
);
// Unchanged: 304, nothing re-parsed, validators sent.
let url = rows[0].meta.feed_url.clone();
let checked = refresh(&f.services, &report.podcast_id, &url, NOW + 1)
.await
.unwrap();
assert!(checked.not_modified);
let second = &f.server.requests("/feed.xml")[1];
assert_eq!(
second.get("if-none-match").map(String::as_str),
Some("\"v1\"")
);
assert_eq!(
second.get("if-modified-since").map(String::as_str),
Some("Sat, 15 Jun 2024 10:00:00 GMT")
);
// Changed: a new episode arrives, the known ones are not duplicated.
f.server.set(
"/feed.xml",
Route::new(
rss(&[("a", "Pilot (remastered)"), ("b", "Second"), ("c", "Third")]),
"application/rss+xml",
)
.etag("\"v2\""),
);
let changed = refresh(&f.services, &report.podcast_id, &url, NOW + 2)
.await
.unwrap();
assert!(!changed.not_modified);
assert_eq!(changed.new_episodes, 1);
assert_eq!(changed.updated_episodes, 1);
assert_eq!(episode_count(store, &report.podcast_id), 3);
// A refresh never writes personal state: no new operation.
assert_eq!(f.log.kinds(), ["podcast_subscription_set"]);
// Subscribing again is recognised without another fetch.
let requests = f.server.requests("/feed.xml").len();
let again = subscribe(&f.services, &f.server.url("/feed.xml"), NOW + 3)
.await
.unwrap();
assert!(again.already_subscribed);
assert_eq!(again.podcast_id, report.podcast_id);
assert_eq!(f.server.requests("/feed.xml").len(), requests);
}
#[tokio::test]
async fn permanent_redirect_becomes_an_alias_and_the_new_fetch_url() {
let f = fixture();
f.server
.set("/old.xml", Route::redirect(301, &f.server.url("/new.xml")));
f.server.set(
"/new.xml",
Route::new(rss(&[("a", "Pilot")]), "application/rss+xml"),
);
let old = FeedUrl::parse(&f.server.url("/old.xml")).unwrap();
let new = FeedUrl::parse(&f.server.url("/new.xml")).unwrap();
let report = subscribe(&f.services, old.as_str(), NOW).await.unwrap();
// The id comes from the URL of the first subscription.
assert_eq!(report.podcast_id, PodcastId::from_feed_url(&old));
assert_eq!(
f.log.kinds(),
["podcast_subscription_set", "podcast_feed_aliases_added"]
);
let store = &f.services.store;
assert!(
store
.feed_aliases(&report.podcast_id)
.unwrap()
.contains(&new)
);
let summary = store.podcast(&report.podcast_id).unwrap().unwrap();
assert_eq!(summary.meta.feed_url, new, "fetched from the new URL now");
assert_eq!(store.resolve_podcast_id(&new).unwrap(), report.podcast_id);
// The next refresh goes straight to the new URL; no new alias op.
let checked = refresh(&f.services, &report.podcast_id, &new, NOW + 1)
.await
.unwrap();
assert!(checked.moved_to.is_none());
assert_eq!(f.server.requests("/old.xml").len(), 1);
assert_eq!(f.log.kinds().len(), 2);
// Subscribing through the new URL finds the same podcast.
let again = subscribe(&f.services, new.as_str(), NOW + 2).await.unwrap();
assert!(again.already_subscribed);
assert_eq!(again.podcast_id, report.podcast_id);
}
/// A feed that moved (301) to a host that answers through a temporary
/// redirect (302, a CDN or tracker) moves to the permanent target only; the
/// following checks start there and are conditional again.
#[tokio::test]
async fn a_permanent_move_behind_a_temporary_redirect_still_moves_the_feed() {
let f = fixture();
f.server.set(
"/old.xml",
Route::redirect(301, &f.server.url("/moved.xml")),
);
f.server
.set("/moved.xml", Route::redirect(302, "/cdn/feed.xml"));
f.server.set(
"/cdn/feed.xml",
Route::new(rss(&[("a", "Pilot")]), "application/rss+xml").etag("\"v1\""),
);
let old = FeedUrl::parse(&f.server.url("/old.xml")).unwrap();
let moved = FeedUrl::parse(&f.server.url("/moved.xml")).unwrap();
let report = subscribe(&f.services, old.as_str(), NOW).await.unwrap();
let store = &f.services.store;
let summary = store.podcast(&report.podcast_id).unwrap().unwrap();
assert_eq!(
summary.meta.feed_url, moved,
"the permanent target, not the CDN"
);
assert!(
store
.feed_aliases(&report.podcast_id)
.unwrap()
.contains(&moved)
);
// Relative enclosures resolve against the document's own address.
let episodes = store
.episodes(&EpisodeQuery::new(report.podcast_id.clone()))
.unwrap();
assert_eq!(episodes[0].episode.audio_url, f.server.url("/audio/a.mp3"));
// The next check starts at the new address and keeps its validators
// through the temporary hop.
let checked = refresh(&f.services, &report.podcast_id, &moved, NOW + 1)
.await
.unwrap();
assert!(checked.not_modified);
assert_eq!(f.server.requests("/old.xml").len(), 1);
let cdn = f.server.requests("/cdn/feed.xml");
assert_eq!(cdn.len(), 2);
assert_eq!(
cdn[1].get("if-none-match").map(String::as_str),
Some("\"v1\"")
);
// A temporary hop first never moves the feed, whatever follows it.
f.server.set(
"/tracked.xml",
Route::redirect(302, &f.server.url("/old.xml")),
);
let tracked = FeedUrl::parse(&f.server.url("/tracked.xml")).unwrap();
let other = subscribe(&f.services, tracked.as_str(), NOW + 2)
.await
.unwrap();
let summary = store.podcast(&other.podcast_id).unwrap().unwrap();
assert_eq!(summary.meta.feed_url, tracked);
}
#[tokio::test]
async fn temporary_redirect_keeps_the_feed_url() {
let f = fixture();
f.server
.set("/tracked.xml", Route::redirect(302, "/real.xml"));
f.server.set(
"/real.xml",
Route::new(rss(&[("a", "Pilot")]), "application/rss+xml"),
);
let tracked = FeedUrl::parse(&f.server.url("/tracked.xml")).unwrap();
let report = subscribe(&f.services, tracked.as_str(), NOW).await.unwrap();
assert_eq!(f.log.kinds(), ["podcast_subscription_set"]);
let summary = f
.services
.store
.podcast(&report.podcast_id)
.unwrap()
.unwrap();
assert_eq!(summary.meta.feed_url, tracked);
// Episode URLs resolve against where the document was served from.
let episodes = f
.services
.store
.episodes(&EpisodeQuery::new(report.podcast_id.clone()))
.unwrap();
assert_eq!(episodes[0].episode.audio_url, f.server.url("/audio/a.mp3"));
}
#[tokio::test]
async fn malformed_feed_and_server_errors_back_off_and_keep_the_catalog() {
let f = fixture();
f.server.set(
"/feed.xml",
Route::new(
rss(&[("a", "Pilot"), ("b", "Second")]),
"application/rss+xml",
),
);
let report = subscribe(&f.services, &f.server.url("/feed.xml"), NOW)
.await
.unwrap();
let id = report.podcast_id;
let url = FeedUrl::parse(&f.server.url("/feed.xml")).unwrap();
f.server.set(
"/feed.xml",
Route::new("<html><body>Moved to our app!</body></html>", "text/html"),
);
let err = refresh(&f.services, &id, &url, NOW + 1).await.unwrap_err();
assert!(format!("{err:#}").contains("unusable feed"), "{err:#}");
let store = &f.services.store;
let state = store.fetch_state(&id).unwrap();
assert_eq!(state.consecutive_failures, 1);
assert!(
state
.last_error
.as_deref()
.unwrap()
.contains("unusable feed")
);
assert_eq!(
state.next_check_at_ms,
Some(next_check_after_failure(NOW + 1, 1, None))
);
assert_eq!(episode_count(store, &id), 2, "an error keeps the catalog");
f.server.set(
"/feed.xml",
Route::new("busy", "text/plain")
.status(503)
.retry_after("7200"),
);
let err = refresh(&f.services, &id, &url, NOW + 2).await.unwrap_err();
assert!(format!("{err:#}").contains("HTTP 503"), "{err:#}");
let state = store.fetch_state(&id).unwrap();
assert_eq!(state.consecutive_failures, 2);
assert_eq!(state.next_check_at_ms, Some(NOW + 2 + 7_200_000));
assert_eq!(episode_count(store, &id), 2);
// A failing feed is not due before its back-off expires.
assert!(
store
.podcasts_due_for_refresh(NOW + 3, 10)
.unwrap()
.is_empty()
);
assert_eq!(
store
.podcasts_due_for_refresh(NOW + 2 + 7_200_000, 10)
.unwrap()
.len(),
1
);
// Recovery clears the error.
f.server.set(
"/feed.xml",
Route::new(
rss(&[("a", "Pilot"), ("b", "Second")]),
"application/rss+xml",
),
);
refresh(&f.services, &id, &url, NOW + 3).await.unwrap();
let state = store.fetch_state(&id).unwrap();
assert_eq!(state.consecutive_failures, 0);
assert!(state.last_error.is_none());
}
#[tokio::test]
async fn subscribing_to_a_non_feed_stores_nothing() {
let f = fixture();
f.server
.set("/page", Route::new("<html>hello</html>", "text/html"));
let err = subscribe(&f.services, &f.server.url("/page"), NOW)
.await
.unwrap_err();
assert!(format!("{err:#}").contains("unusable feed"), "{err:#}");
let err = subscribe(&f.services, &f.server.url("/missing"), NOW)
.await
.unwrap_err();
assert!(format!("{err:#}").contains("HTTP 404"), "{err:#}");
let err = subscribe(&f.services, "ftp://example.test/feed", NOW)
.await
.unwrap_err();
assert!(!format!("{err:#}").is_empty());
assert!(
f.services
.store
.list_podcasts(PodcastListFilter::All)
.unwrap()
.is_empty()
);
assert!(f.log.kinds().is_empty());
}
#[tokio::test]
async fn unsubscribe_then_resubscribe_keeps_the_podcast_id() {
let f = fixture();
f.server.set(
"/feed.xml",
Route::new(rss(&[("a", "Pilot")]), "application/rss+xml"),
);
let first = subscribe(&f.services, &f.server.url("/feed.xml"), NOW)
.await
.unwrap();
let store = Arc::clone(&f.services.store);
let id = first.podcast_id.clone();
f.log
.record(&mut |stamps| store.unsubscribe(stamps, &id))
.unwrap();
assert!(
store
.list_podcasts(PodcastListFilter::Subscribed)
.unwrap()
.is_empty()
);
let again = subscribe(&f.services, &f.server.url("/feed.xml"), NOW + 1)
.await
.unwrap();
assert!(!again.already_subscribed);
assert_eq!(again.podcast_id, first.podcast_id);
assert_eq!(
f.log.kinds(),
[
"podcast_subscription_set",
"podcast_subscription_set",
"podcast_share_set",
"podcast_subscription_set"
]
);
let ops = f.log.ops.lock().unwrap();
assert!(matches!(
ops.last().map(|op| &op.payload),
Some(SyncOpPayload::PodcastSubscriptionSet {
subscribed: true,
..
})
));
}
#[test]
fn back_off_doubles_and_honours_retry_after() {
let base = FAILURE_BACKOFF_BASE.as_millis() as i64;
assert_eq!(next_check_after_failure(0, 1, None), base);
assert_eq!(next_check_after_failure(0, 2, None), 2 * base);
assert_eq!(next_check_after_failure(0, 4, None), 8 * base);
let max = FAILURE_BACKOFF_MAX.as_millis() as i64;
assert_eq!(next_check_after_failure(0, 40, None), max);
assert_eq!(
next_check_after_failure(0, 1, Some(Duration::from_secs(3_600))),
3_600_000
);
assert_eq!(
next_check_after_failure(0, 1, Some(Duration::from_secs(10 * 86_400))),
max
);
assert_eq!(
next_check_after_success(0),
REFRESH_INTERVAL.as_millis() as i64
);
}
/// The prototype podcast build's schema (user_version 1), verbatim.
const PROTOTYPE_SCHEMA: &str = "
CREATE TABLE IF NOT EXISTS podcasts (
id INTEGER PRIMARY KEY AUTOINCREMENT,
feed_url TEXT NOT NULL UNIQUE,
title TEXT NOT NULL,
author TEXT,
description TEXT,
link TEXT,
image_url TEXT,
cover_url TEXT,
cover_path TEXT,
etag TEXT,
last_modified TEXT,
added_at INTEGER NOT NULL,
last_checked_at INTEGER,
last_error TEXT
);
CREATE TABLE IF NOT EXISTS podcast_episodes (
id INTEGER PRIMARY KEY AUTOINCREMENT,
podcast_id INTEGER NOT NULL REFERENCES podcasts(id) ON DELETE CASCADE,
guid TEXT NOT NULL,
title TEXT NOT NULL,
description TEXT,
published_at INTEGER,
duration_seconds REAL,
audio_url TEXT NOT NULL,
mime_type TEXT,
byte_len INTEGER,
link TEXT,
image_url TEXT,
first_seen_at INTEGER NOT NULL,
UNIQUE (podcast_id, guid)
);
CREATE INDEX IF NOT EXISTS podcast_episodes_by_date
ON podcast_episodes (podcast_id, published_at DESC, id DESC);
";
#[test]
fn prototype_database_is_migrated_in_place() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join(furumi_library::podcasts::PODCAST_DB_FILE);
{
let conn = rusqlite::Connection::open(&path).unwrap();
conn.execute_batch(PROTOTYPE_SCHEMA).unwrap();
conn.execute(
"INSERT INTO podcasts (feed_url, title, etag, added_at, last_checked_at)
VALUES ('https://example.test/feed.xml', 'Old Show', '\"e1\"', 1700000000, 1700000100)",
[],
)
.unwrap();
conn.execute(
"INSERT INTO podcast_episodes
(podcast_id, guid, title, published_at, duration_seconds, audio_url, first_seen_at)
VALUES (1, 'ep-1', 'Old Pilot', 1700000000, 1800.0,
'https://example.test/1.mp3', 1700000000)",
[],
)
.unwrap();
conn.pragma_update(None, "user_version", 1).unwrap();
}
let services = super::open_services(
&path,
dir.path().join("covers"),
Arc::new(MemoryLog::default()),
)
.unwrap();
let store = &services.store;
assert_eq!(
store.schema_version().unwrap(),
furumi_library::podcasts::PODCAST_SCHEMA_VERSION
);
let rows = store.list_podcasts(PodcastListFilter::Subscribed).unwrap();
assert_eq!(rows.len(), 1);
assert_eq!(rows[0].meta.title, "Old Show");
assert_eq!(rows[0].episode_count, 1);
let expected =
PodcastId::from_feed_url(&FeedUrl::parse("https://example.test/feed.xml").unwrap());
assert_eq!(rows[0].podcast_id, expected);
// The prototype's validators are dropped: the first check parses the
// feed (`imported_podcasts_get_their_seasons_on_the_first_check`).
let fetch = store.fetch_state(&expected).unwrap();
assert_eq!(fetch.etag, None);
assert_eq!(fetch.last_success_at_ms, Some(1_700_000_100_000));
assert_eq!(fetch.next_check_at_ms, None, "due at once");
drop(services);
// The original rows are kept, renamed.
let conn = rusqlite::Connection::open(&path).unwrap();
let legacy: i64 = conn
.query_row("SELECT COUNT(*) FROM legacy_podcast_episodes", [], |row| {
row.get(0)
})
.unwrap();
assert_eq!(legacy, 1);
}
#[test]
fn foreign_or_newer_databases_are_refused_unchanged() {
let dir = tempfile::tempdir().unwrap();
let log: Arc<dyn OpLog> = Arc::new(MemoryLog::default());
let foreign = dir.path().join("foreign.sqlite3");
{
let conn = rusqlite::Connection::open(&foreign).unwrap();
conn.execute_batch("CREATE TABLE tracks (id INTEGER PRIMARY KEY, title TEXT);")
.unwrap();
}
let newer = dir.path().join("newer.sqlite3");
{
let conn = rusqlite::Connection::open(&newer).unwrap();
conn.pragma_update(None, "user_version", 99).unwrap();
}
let garbage = dir.path().join("garbage.sqlite3");
std::fs::write(
&garbage,
b"this is not a database at all, just some text bytes",
)
.unwrap();
for (path, expected) in [
(&foreign, "not a Furumi podcast database"),
(&newer, "newer than this Furumi supports"),
(&garbage, ""),
] {
let before = std::fs::read(path).unwrap();
let Err(err) = super::open_services(path, dir.path().join("covers"), Arc::clone(&log))
else {
panic!("{} opened", path.display());
};
let message = super::describe_open_error(&err);
assert!(message.contains(expected), "{message}");
assert_eq!(std::fs::read(path).unwrap(), before, "{}", path.display());
}
}
/// A prototype database knew no seasons or episode numbers. Its stored
/// `ETag` would make the first check "304 Not Modified" forever for a feed
/// that no longer changes, so the seasons would never appear.
#[tokio::test]
async fn imported_podcasts_get_their_seasons_on_the_first_check() {
let dir = tempfile::tempdir().unwrap();
let server = TestServer::start();
let feed = "<?xml version=\"1.0\"?><rss version=\"2.0\" \
xmlns:itunes=\"http://www.itunes.com/dtds/podcast-1.0.dtd\"><channel>\
<title>Old Show</title><item><title>Old Pilot</title><guid>ep-1</guid>\
<pubDate>Sat, 15 Jun 2024 10:00:00 GMT</pubDate>\
<itunes:season>1</itunes:season><itunes:episode>1</itunes:episode>\
<enclosure url=\"/audio/1.mp3\" type=\"audio/mpeg\" length=\"100\"/></item>\
</channel></rss>";
// The server answers the prototype's validator with 304.
server.set(
"/feed.xml",
Route::new(feed, "application/rss+xml").etag("\"e1\""),
);
let feed_url = server.url("/feed.xml");
let path = dir.path().join(furumi_library::podcasts::PODCAST_DB_FILE);
{
let conn = rusqlite::Connection::open(&path).unwrap();
conn.execute_batch(PROTOTYPE_SCHEMA).unwrap();
conn.execute(
"INSERT INTO podcasts (feed_url, title, etag, last_modified, added_at, last_checked_at)
VALUES (?1, 'Old Show', '\"e1\"', 'Sat, 15 Jun 2024 10:00:00 GMT',
1700000000, 1700000100)",
[&feed_url],
)
.unwrap();
conn.execute(
"INSERT INTO podcast_episodes
(podcast_id, guid, title, published_at, duration_seconds, audio_url, first_seen_at)
VALUES (1, 'ep-1', 'Old Pilot', 1718445600, 1800.0, ?1, 1700000000)",
[server.url("/audio/1.mp3")],
)
.unwrap();
conn.pragma_update(None, "user_version", 1).unwrap();
}
let services = super::open_services(
&path,
dir.path().join("covers"),
Arc::new(MemoryLog::default()),
)
.unwrap();
let store = Arc::clone(&services.store);
let id = PodcastId::from_feed_url(&FeedUrl::parse(&feed_url).unwrap());
assert!(
store
.seasons(&id)
.unwrap()
.iter()
.all(|s| s.season.is_none()),
"the prototype had no seasons"
);
let due = store.podcasts_due_for_refresh(NOW, 16).unwrap();
assert_eq!(due.len(), 1);
let report = refresh(&services, &id, &due[0].1, NOW).await.unwrap();
assert!(!report.not_modified);
let requests = server.requests("/feed.xml");
assert_eq!(requests.len(), 1);
assert!(!requests[0].contains_key("if-none-match"));
assert!(!requests[0].contains_key("if-modified-since"));
let seasons = store.seasons(&id).unwrap();
assert_eq!(
seasons.iter().map(|s| s.season).collect::<Vec<_>>(),
[Some(1)]
);
// From then on the checks are conditional again.
let report = refresh(&services, &id, &due[0].1, NOW + 1).await.unwrap();
assert!(report.not_modified);
drop(services);
// A store that was already migrated keeps its validators on reopen.
let services = super::open_services(
&path,
dir.path().join("covers"),
Arc::new(MemoryLog::default()),
)
.unwrap();
assert_eq!(
services.store.fetch_state(&id).unwrap().etag.as_deref(),
Some("\"e1\"")
);
}
/// The import commits inside `PodcastStore::open` and the validators are
/// dropped afterwards. A start that stopped in between (killed, or a failed
/// write) finishes the job at the next start, and the imported back-off is
/// kept.
#[test]
fn dropping_prototype_validators_resumes_after_an_interrupted_start() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join(furumi_library::podcasts::PODCAST_DB_FILE);
{
let conn = rusqlite::Connection::open(&path).unwrap();
conn.execute_batch(PROTOTYPE_SCHEMA).unwrap();
conn.execute(
"INSERT INTO podcasts (feed_url, title, etag, added_at, last_checked_at)
VALUES ('https://example.test/ok.xml', 'Fine Show', '\"e1\"', 1700000000, 1700000100)",
[],
)
.unwrap();
conn.execute(
"INSERT INTO podcasts
(feed_url, title, last_modified, added_at, last_checked_at, last_error)
VALUES ('https://example.test/broken.xml', 'Broken Show',
'Sat, 15 Jun 2024 10:00:00 GMT', 1700000000, 1700000200, 'HTTP 500')",
[],
)
.unwrap();
conn.pragma_update(None, "user_version", 1).unwrap();
}
let ok = PodcastId::from_feed_url(&FeedUrl::parse("https://example.test/ok.xml").unwrap());
let broken =
PodcastId::from_feed_url(&FeedUrl::parse("https://example.test/broken.xml").unwrap());
// The first start: the marker is written, then the import commits, and
// the process stops before the validators are dropped.
let marker = super::validators_marker(&path);
assert!(super::is_prototype_database(&path));
std::fs::write(&marker, b"").unwrap();
drop(PodcastStore::open(&path).unwrap());
assert!(!super::is_prototype_database(&path), "migrated");
// The next start finishes the job.
let services = super::open_services(
&path,
dir.path().join("covers"),
Arc::new(MemoryLog::default()),
)
.unwrap();
let store = &services.store;
let fetch = store.fetch_state(&ok).unwrap();
assert_eq!(fetch.etag, None);
assert_eq!(fetch.last_error, None);
let fetch = store.fetch_state(&broken).unwrap();
assert_eq!(fetch.last_modified, None);
assert_eq!(fetch.last_error.as_deref(), Some("HTTP 500"));
assert_eq!(
fetch.consecutive_failures, 1,
"the imported back-off is kept"
);
assert_eq!(fetch.checked_at_ms, Some(1_700_000_200_000));
assert!(!marker.exists(), "done once");
// Validators of later checks are kept on every start after that.
store
.record_fetch_success(&ok, NOW, Some("\"e2\""), None, None)
.unwrap();
drop(services);
let services = super::open_services(
&path,
dir.path().join("covers"),
Arc::new(MemoryLog::default()),
)
.unwrap();
assert_eq!(
services.store.fetch_state(&ok).unwrap().etag.as_deref(),
Some("\"e2\"")
);
}
fn feed_url(f: &Fixture, path: &str) -> FeedUrl {
FeedUrl::parse(&f.server.url(path)).unwrap()
}
#[tokio::test]
async fn feeds_over_the_size_limit_are_refused_with_or_without_a_length() {
let f = fixture();
f.server.set(
"/feed.xml",
Route::new(rss(&[("a", "Pilot")]), "application/rss+xml"),
);
let url = feed_url(&f, "/feed.xml");
let id = subscribe(&f.services, url.as_str(), NOW)
.await
.unwrap()
.podcast_id;
let mut huge = rss(&[("a", "Pilot"), ("b", "Second")]);
huge.resize(MAX_FEED_BYTES + 1, b' ');
let store = &f.services.store;
for (attempt, route) in [
Route::new(huge.clone(), "application/rss+xml"),
Route::new(huge, "application/rss+xml").no_length(),
]
.into_iter()
.enumerate()
{
let failures = attempt as u32 + 1;
f.server.set("/feed.xml", route);
let now = NOW + i64::from(failures);
let err = refresh(&f.services, &id, &url, now).await.unwrap_err();
assert!(format!("{err:#}").contains("too large"), "{err:#}");
let state = store.fetch_state(&id).unwrap();
assert_eq!(state.consecutive_failures, failures);
assert!(state.last_error.unwrap().contains("too large"));
assert_eq!(
state.next_check_at_ms,
Some(next_check_after_failure(now, failures, None))
);
assert_eq!(episode_count(store, &id), 1, "the catalog is kept");
}
}
#[tokio::test]
async fn redirect_chains_are_bounded_and_lead_only_to_http() {
let f = fixture();
let fetch = |path: &'static str| {
let url = feed_url(&f, path);
let fetcher = std::sync::Arc::clone(&f.services.fetcher);
async move { fetcher.fetch_feed(&url, Validators::default()).await }
};
for n in 0..=MAX_REDIRECTS {
f.server.set(
&format!("/r{n}.xml"),
Route::redirect(302, &format!("/r{}.xml", n + 1)),
);
}
f.server.set(
&format!("/r{}.xml", MAX_REDIRECTS + 1),
Route::new(rss(&[("a", "Pilot")]), "application/rss+xml"),
);
// MAX_REDIRECTS hops are followed, one more is refused.
let followed = fetch("/r1.xml").await.unwrap();
assert_eq!(followed.redirects, MAX_REDIRECTS);
let err = fetch("/r0.xml").await.unwrap_err();
assert!(format!("{err:#}").contains("too many redirects"), "{err:#}");
// A loop ends the same way.
f.server.set("/a.xml", Route::redirect(301, "/b.xml"));
f.server.set("/b.xml", Route::redirect(301, "/a.xml"));
let err = fetch("/a.xml").await.unwrap_err();
assert!(format!("{err:#}").contains("too many redirects"), "{err:#}");
assert_eq!(f.server.requests("/a.xml").len(), MAX_REDIRECTS / 2 + 1);
// Only http(s) is followed.
f.server.set(
"/ftp.xml",
Route::redirect(302, "ftp://example.test/feed.xml"),
);
let err = fetch("/ftp.xml").await.unwrap_err();
assert!(
format!("{err:#}").contains("unsupported URL scheme"),
"{err:#}"
);
// Subscribing through any of them stores nothing.
for path in ["/r0.xml", "/a.xml", "/ftp.xml"] {
assert!(
subscribe(&f.services, &f.server.url(path), NOW)
.await
.is_err()
);
}
assert!(
f.services
.store
.list_podcasts(PodcastListFilter::All)
.unwrap()
.is_empty()
);
}
#[tokio::test]
async fn a_hanging_server_fails_the_check_at_the_deadline() {
let f = fixture();
f.server.set(
"/feed.xml",
Route::new(rss(&[("a", "Pilot")]), "application/rss+xml"),
);
let url = feed_url(&f, "/feed.xml");
let id = subscribe(&f.services, url.as_str(), NOW)
.await
.unwrap()
.podcast_id;
f.server.set(
"/feed.xml",
Route::new(rss(&[("a", "Pilot")]), "application/rss+xml")
.stall(FETCH_DEADLINE + Duration::from_secs(5)),
);
let started = std::time::Instant::now();
let err = refresh(&f.services, &id, &url, NOW + 1).await.unwrap_err();
assert!(format!("{err:#}").contains("took longer than"), "{err:#}");
assert!(started.elapsed() < FETCH_DEADLINE + Duration::from_secs(2));
let state = f.services.store.fetch_state(&id).unwrap();
assert_eq!(state.consecutive_failures, 1);
assert_eq!(episode_count(&f.services.store, &id), 1);
}
#[tokio::test]
async fn covers_must_be_images_within_the_limit_and_are_written_whole() {
let f = fixture();
let png = {
let mut out = std::io::Cursor::new(Vec::new());
image::RgbImage::new(2, 2)
.write_to(&mut out, image::ImageFormat::Png)
.unwrap();
out.into_inner()
};
f.server
.set("/cover.png", Route::new(png.clone(), "image/png"));
f.server.set(
"/page.png",
Route::new("<html>not an image</html>", "image/png"),
);
f.server.set(
"/huge.png",
Route::new(vec![0u8; MAX_COVER_BYTES + 1], "image/png"),
);
let id = PodcastId::from_feed_url(&feed_url(&f, "/feed.xml"));
let fetcher = &f.services.fetcher;
let path = fetcher
.fetch_cover(&id, &f.server.url("/cover.png"))
.await
.unwrap();
assert_eq!(std::fs::read(&path).unwrap(), png);
assert_eq!(path.extension().unwrap(), "png");
let err = fetcher
.fetch_cover(&id, &f.server.url("/page.png"))
.await
.unwrap_err();
assert!(
format!("{err:#}").contains("not a supported image"),
"{err:#}"
);
let err = fetcher
.fetch_cover(&id, &f.server.url("/huge.png"))
.await
.unwrap_err();
assert!(format!("{err:#}").contains("too large"), "{err:#}");
// Only the one finished file: nothing partial, no temporary files.
let files: Vec<_> = std::fs::read_dir(path.parent().unwrap())
.unwrap()
.map(|entry| entry.unwrap().path())
.collect();
assert_eq!(files, [path]);
}
+253
View File
@@ -0,0 +1,253 @@
use crate::library::models::TrackItem;
/// Content id of a music track. Podcast episodes have none: they are not
/// content-addressed and never shared as `frid://` track links.
pub fn track_content_id(track: &TrackItem) -> Option<String> {
if track.is_podcast() {
return None;
}
track
.fed
.as_ref()
.and_then(|fed| fed.content_id.as_deref())
.or(track.content_id.as_deref())
.and_then(music_dht::normalize_content_id)
}
pub fn track_can_share(track: &TrackItem) -> bool {
track_content_id(track).is_some() || !track.file_path.trim().is_empty()
}
pub fn track_share_link(track: &TrackItem) -> Option<String> {
if track.is_podcast() {
return None;
}
let content_id = track_content_id(track).or_else(|| {
(!track.file_path.trim().is_empty())
.then(|| crate::library::audio_content_id(&track.file_path))
.flatten()
})?;
Some(track_share_link_for_content_id(track, &content_id))
}
/// A parsed `frid://` share link.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FridLink {
/// Canonical content id (`b3:<64 hex>`).
pub content_id: String,
/// Human-readable "artists-title" label from the `t` query parameter.
pub label: Option<String>,
}
pub fn parse_frid_link(value: &str) -> Option<FridLink> {
let value = value.trim();
let rest = value.strip_prefix("frid://")?;
let mut parts = rest.splitn(2, ['?', '#']);
let content_id =
music_dht::normalize_content_id(parts.next().unwrap_or_default().trim_end_matches('/'))?;
let label = parts.next().and_then(|query| {
query.split('&').find_map(|pair| {
let value = pair.strip_prefix("t=")?;
let decoded = percent_decode(value);
let decoded = decoded.trim();
(!decoded.is_empty()).then(|| decoded.to_string())
})
});
Some(FridLink { content_id, label })
}
pub fn cached_track_share_link(track: &TrackItem) -> Option<String> {
let content_id = track_content_id(track)?;
Some(track_share_link_for_content_id(track, &content_id))
}
fn track_share_link_for_content_id(track: &TrackItem, content_id: &str) -> String {
let label = track_share_label(track);
if label.is_empty() {
format!("frid://{content_id}")
} else {
format!("frid://{content_id}?t={}", percent_encode(&label))
}
}
fn track_share_label(track: &TrackItem) -> String {
let artists = track.artist_line();
let title = track.title.trim();
match (artists.trim().is_empty(), title.is_empty()) {
(false, false) => format!("{}-{title}", artists.trim()),
(true, false) => title.to_string(),
(false, true) => artists.trim().to_string(),
(true, true) => String::new(),
}
}
fn percent_encode(value: &str) -> String {
let mut out = String::new();
for byte in value.as_bytes() {
match *byte {
b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => {
out.push(char::from(*byte))
}
byte => out.push_str(&format!("%{byte:02X}")),
}
}
out
}
fn percent_decode(value: &str) -> String {
let bytes = value.as_bytes();
let mut out = Vec::with_capacity(bytes.len());
let mut index = 0;
while index < bytes.len() {
match bytes[index] {
b'%' if index + 3 <= bytes.len() => {
let hex = std::str::from_utf8(&bytes[index + 1..index + 3])
.ok()
.and_then(|hex| u8::from_str_radix(hex, 16).ok());
match hex {
Some(byte) => {
out.push(byte);
index += 3;
}
None => {
out.push(b'%');
index += 1;
}
}
}
// Liberal form-encoding acceptance; our encoder never emits '+'.
b'+' => {
out.push(b' ');
index += 1;
}
byte => {
out.push(byte);
index += 1;
}
}
}
String::from_utf8_lossy(&out).into_owned()
}
#[cfg(test)]
mod tests {
use super::*;
use crate::library::models::ArtistRef;
#[test]
fn share_link_uses_content_id_and_readable_label() {
let track = TrackItem {
id: 1,
title: "Трек".into(),
track_number: None,
disc_number: None,
duration_seconds: 1.0,
artists: vec![ArtistRef {
id: 1,
name: "Артист".into(),
}],
featured_artists: Vec::new(),
release_id: 1,
release_title: "Release".into(),
release_year: None,
file_path: String::new(),
content_id: Some(
"b3:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef".into(),
),
cover_path: None,
audio_format: None,
audio_bitrate: None,
audio_sample_rate: None,
audio_bit_depth: None,
file_size_bytes: None,
play_count: 0,
fed: None,
podcast: None,
};
assert_eq!(
track_share_link(&track).as_deref(),
Some(
"frid://b3:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef?t=%D0%90%D1%80%D1%82%D0%B8%D1%81%D1%82-%D0%A2%D1%80%D0%B5%D0%BA"
)
);
}
#[test]
fn parses_frid_content_link() {
let link = parse_frid_link(
"frid://b3:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef?t=Artist-Track"
)
.expect("valid link");
assert_eq!(
link.content_id,
"b3:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
);
assert_eq!(link.label.as_deref(), Some("Artist-Track"));
assert!(parse_frid_link("https://example.com").is_none());
}
#[test]
fn parses_percent_encoded_label() {
let link = parse_frid_link(
"frid://B3:0123456789ABCDEF0123456789abcdef0123456789abcdef0123456789abcdef?t=Rammstein-Du%20Riechst%20So%20Gut"
)
.expect("valid link");
assert_eq!(
link.content_id,
"b3:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
);
assert_eq!(link.label.as_deref(), Some("Rammstein-Du Riechst So Gut"));
// Cyrillic labels and a missing label both survive.
let link = parse_frid_link(
"frid://b3:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef?t=%D0%90%D1%80%D1%82%D0%B8%D1%81%D1%82"
)
.expect("valid link");
assert_eq!(link.label.as_deref(), Some("Артист"));
let link = parse_frid_link(
"frid://b3:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
)
.expect("valid link");
assert_eq!(link.label, None);
}
#[test]
fn share_link_round_trips_through_parse() {
let track = TrackItem {
id: 1,
title: "Du Riechst So Gut".into(),
track_number: None,
disc_number: None,
duration_seconds: 1.0,
artists: vec![ArtistRef {
id: 1,
name: "Rammstein".into(),
}],
featured_artists: Vec::new(),
release_id: 1,
release_title: "Herzeleid".into(),
release_year: None,
file_path: String::new(),
content_id: Some(
"b3:5ebd9e61e1154a64470e6ee4dd1225550f380dd575d01fd4ffba6a5bd1b34104".into(),
),
cover_path: None,
audio_format: None,
audio_bitrate: None,
audio_sample_rate: None,
audio_bit_depth: None,
file_size_bytes: None,
play_count: 0,
fed: None,
podcast: None,
};
let link = track_share_link(&track).expect("link");
let parsed = parse_frid_link(&link).expect("parses back");
assert_eq!(
parsed.content_id,
"b3:5ebd9e61e1154a64470e6ee4dd1225550f380dd575d01fd4ffba6a5bd1b34104"
);
assert_eq!(parsed.label.as_deref(), Some("Rammstein-Du Riechst So Gut"));
}
}
+1196
View File
File diff suppressed because it is too large. Load diff
+190
View File
@@ -0,0 +1,190 @@
//! Cheap now-playing export for status bars and other polling clients.
//!
//! The UI only sends snapshots through a bounded channel. A dedicated thread
//! performs the filesystem writes so a slow filesystem cannot stall drawing
//! or input handling.
use std::fs;
use std::io;
use std::path::PathBuf;
use std::sync::mpsc::{self, SyncSender, TrySendError};
use std::time::{SystemTime, UNIX_EPOCH};
use serde::{Deserialize, Serialize};
use crate::app::state::PlayerBar;
const STALE_AFTER_MS: u64 = 5_000;
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct PlaybackStatus {
pub playing: bool,
pub paused: bool,
pub title: String,
pub artist: String,
pub album: String,
pub position_secs: f64,
pub duration_secs: f64,
pub volume: u8,
pub updated_at_ms: u64,
}
impl PlaybackStatus {
pub fn from_player(player: &PlayerBar) -> Option<Self> {
let track = player.current.as_ref()?;
player.playing.then(|| Self {
playing: true,
paused: player.paused,
title: track.title.clone(),
artist: track.artist_line(),
album: track.release_title.clone(),
position_secs: player.position_secs.max(0.0),
duration_secs: track.duration_seconds.max(0.0),
volume: player.volume,
updated_at_ms: now_ms(),
})
}
pub fn one_line(&self) -> String {
let icon = if self.paused { "⏸" } else { "▶" };
let track = if self.artist.is_empty() {
self.title.clone()
} else {
format!("{} — {}", self.artist, self.title)
};
format!(
"{icon} {track} {}/{}",
duration(self.position_secs),
duration(self.duration_secs)
)
}
}
pub struct Publisher {
tx: Option<SyncSender<Option<PlaybackStatus>>>,
}
impl Publisher {
pub fn spawn() -> Self {
let (tx, rx) = mpsc::sync_channel(1);
std::thread::Builder::new()
.name("playback-status".to_string())
.spawn(move || {
while let Ok(snapshot) = rx.recv() {
if let Some(snapshot) = snapshot {
if let Err(err) = write(&snapshot) {
tracing::debug!(?err, "writing playback status failed");
}
} else {
remove();
}
}
remove();
})
.ok();
Self { tx: Some(tx) }
}
pub fn publish(&self, snapshot: Option<PlaybackStatus>) {
let Some(tx) = &self.tx else { return };
match tx.try_send(snapshot) {
Ok(()) | Err(TrySendError::Full(_)) => {}
Err(TrySendError::Disconnected(_)) => {}
}
}
}
impl Drop for Publisher {
fn drop(&mut self) {
self.tx.take();
}
}
pub fn print(json: bool) -> anyhow::Result<()> {
let Some(status) = read()? else {
return Ok(());
};
if json {
println!("{}", serde_json::to_string(&status)?);
} else {
println!("{}", status.one_line());
}
Ok(())
}
fn read() -> anyhow::Result<Option<PlaybackStatus>> {
let Some(path) = path() else {
return Ok(None);
};
let bytes = match fs::read(path) {
Ok(bytes) => bytes,
Err(err) if err.kind() == io::ErrorKind::NotFound => return Ok(None),
Err(err) => return Err(err.into()),
};
let status: PlaybackStatus = serde_json::from_slice(&bytes)?;
if now_ms().saturating_sub(status.updated_at_ms) > STALE_AFTER_MS {
return Ok(None);
}
Ok(Some(status))
}
fn write(status: &PlaybackStatus) -> anyhow::Result<()> {
let Some(path) = path() else {
return Ok(());
};
let Some(dir) = path.parent() else {
return Ok(());
};
fs::create_dir_all(dir)?;
let temporary = dir.join("playback-status.tmp");
fs::write(&temporary, serde_json::to_vec(status)?)?;
#[cfg(windows)]
if path.exists() {
let _ = fs::remove_file(&path);
}
fs::rename(temporary, path)?;
Ok(())
}
fn remove() {
if let Some(path) = path() {
let _ = fs::remove_file(path);
}
}
fn path() -> Option<PathBuf> {
crate::config::project_dirs().map(|dirs| dirs.cache_dir().join("playback-status.json"))
}
fn now_ms() -> u64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|duration| duration.as_millis() as u64)
.unwrap_or(0)
}
fn duration(seconds: f64) -> String {
let total = seconds.max(0.0).round() as u64;
format!("{}:{:02}", total / 60, total % 60)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn one_line_contains_state_metadata_and_progress() {
let status = PlaybackStatus {
playing: true,
paused: true,
title: "Track".into(),
artist: "Artist".into(),
album: "Release".into(),
position_secs: 83.0,
duration_secs: 245.0,
volume: 80,
updated_at_ms: 0,
};
assert_eq!(status.one_line(), "⏸ Artist — Track 1:23/4:05");
}
}
+166
View File
@@ -0,0 +1,166 @@
use std::fs::File;
use std::io::{self, Read, Seek, SeekFrom};
use std::path::Path;
use std::sync::{Arc, Condvar, Mutex};
#[derive(Debug, Default)]
struct State {
available: u64,
complete: bool,
}
#[derive(Debug, Default)]
struct Shared {
state: Mutex<State>,
changed: Condvar,
}
#[derive(Debug)]
pub struct GrowingFileReader {
file: File,
pos: u64,
shared: Arc<Shared>,
}
#[derive(Debug)]
pub struct GrowingFileWriter {
shared: Arc<Shared>,
}
pub fn growing_file(path: &Path) -> io::Result<(GrowingFileReader, GrowingFileWriter)> {
let file = File::open(path)?;
let shared = Arc::new(Shared::default());
Ok((
GrowingFileReader {
file,
pos: 0,
shared: Arc::clone(&shared),
},
GrowingFileWriter { shared },
))
}
impl GrowingFileWriter {
pub fn add_available(&self, bytes: u64) {
let mut state = self
.shared
.state
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner);
state.available = state.available.saturating_add(bytes);
self.shared.changed.notify_all();
}
pub fn finish(&self) {
let mut state = self
.shared
.state
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner);
state.complete = true;
self.shared.changed.notify_all();
}
}
impl Drop for GrowingFileWriter {
fn drop(&mut self) {
self.finish();
}
}
impl Read for GrowingFileReader {
fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
if buf.is_empty() {
return Ok(0);
}
loop {
let mut state = self
.shared
.state
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner);
while self.pos >= state.available && !state.complete {
state = self
.shared
.changed
.wait(state)
.unwrap_or_else(std::sync::PoisonError::into_inner);
}
if self.pos >= state.available && state.complete {
return Ok(0);
}
let readable = (state.available - self.pos).min(buf.len() as u64) as usize;
drop(state);
let read = self.file.read(&mut buf[..readable])?;
self.pos = self.pos.saturating_add(read as u64);
if read > 0 {
return Ok(read);
}
}
}
}
impl Seek for GrowingFileReader {
fn seek(&mut self, position: SeekFrom) -> io::Result<u64> {
// Random access beyond the downloaded prefix is intentionally not
// exposed, but decoders may inspect and rewind the available header.
let available = self
.shared
.state
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.available;
let target = match position {
SeekFrom::Start(position) => i128::from(position),
SeekFrom::Current(offset) => i128::from(self.pos) + i128::from(offset),
SeekFrom::End(offset) => i128::from(available) + i128::from(offset),
};
if target < 0 || target > i128::from(available) {
return Err(io::Error::new(
io::ErrorKind::Unsupported,
"cannot seek outside the downloaded audio prefix",
));
}
let target = target as u64;
self.file.seek(SeekFrom::Start(target))?;
self.pos = target;
Ok(target)
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::io::{Read, Write};
#[test]
fn growing_reader_reads_available_bytes_then_eof() {
let path =
std::env::temp_dir().join(format!("furumi-growing-reader-{}", std::process::id()));
let _ = std::fs::remove_file(&path);
std::fs::File::create(&path).unwrap();
let (mut reader, writer) = growing_file(&path).unwrap();
let mut output = std::fs::OpenOptions::new().write(true).open(&path).unwrap();
output.write_all(b"fur").unwrap();
writer.add_available(3);
let mut first = [0u8; 3];
reader.read_exact(&mut first).unwrap();
assert_eq!(&first, b"fur");
reader.seek(SeekFrom::Start(0)).unwrap();
let mut rewind = [0u8; 3];
reader.read_exact(&mut rewind).unwrap();
assert_eq!(&rewind, b"fur");
assert!(reader.seek(SeekFrom::Start(4)).is_err());
output.write_all(b"umi").unwrap();
writer.add_available(3);
writer.finish();
let mut rest = Vec::new();
reader.read_to_end(&mut rest).unwrap();
assert_eq!(&rest, b"umi");
drop(output);
let _ = std::fs::remove_file(&path);
}
}
+191
View File
@@ -0,0 +1,191 @@
//! Secondary settings window; child dialogs are rendered above it.
use ratatui::{
Frame,
layout::{Constraint, Layout, Rect},
text::Line,
widgets::{Block, Clear, List, ListItem, ListState, Paragraph, Wrap},
};
use super::theme;
use crate::app::state::{AppState, SettingsRow, additional_settings_rows};
pub fn draw(frame: &mut Frame, state: &AppState) {
let screen = frame.area();
let width = screen.width.saturating_sub(2).min(90);
let height = screen.height.saturating_sub(2).min(26);
let area = Rect::new(
screen.x + (screen.width - width) / 2,
screen.y + (screen.height - height) / 2,
width,
height,
);
let block = Block::bordered()
.title(" Additional settings ")
.title_style(theme::header_for(state))
.border_style(theme::strong_border_for(state));
let inner = block.inner(area);
frame.render_widget(Clear, area);
frame.render_widget(block, area);
let [list_area, status_area, footer] = Layout::vertical([
Constraint::Min(1),
Constraint::Length(3),
Constraint::Length(1),
])
.areas(inner);
let rows = additional_settings_rows(state);
let mut items = Vec::new();
let mut selected = 0;
for (index, row) in rows.iter().enumerate() {
let section = match row {
SettingsRow::MusicDirectory => Some("Library"),
SettingsRow::CheckUpdate => Some("Updates"),
SettingsRow::VisualizationClock => Some("Visualizations"),
_ => None,
};
if let Some(section) = section {
items.push(ListItem::new(Line::styled(
section,
theme::header_for(state),
)));
}
if index
== state
.additional_settings_cursor
.min(rows.len().saturating_sub(1))
{
selected = items.len();
}
let (label, value, enabled) = match row {
SettingsRow::MusicDirectory => (
"Music save directory".into(),
if state.music_dir_changing {
"checking/changing...".into()
} else {
state.music_dir.to_string_lossy().into_owned()
},
!state.music_dir_changing,
),
SettingsRow::CheckUpdate => (
"Check for updates".into(),
format!("v{}", env!("CARGO_PKG_VERSION")),
!state.updater.busy && !state.updater.installed,
),
SettingsRow::InstallUpdate => (
"Install update".into(),
state
.updater
.available
.as_ref()
.map(|u| format!("v{}", u.version))
.unwrap_or_else(|| "check for updates first".into()),
state.updater.available.is_some()
&& !state.updater.busy
&& !state.updater.installed,
),
SettingsRow::VisualizationClock => (
"Show clock".into(),
if state.visualizer.config.show_clock {
"on"
} else {
"off"
}
.into(),
true,
),
SettingsRow::VisualizationScript(index) => {
let script = &state.visualizer.scripts[*index];
let mark = if state.visualizer.selected_script_index() == Some(*index) {
"* "
} else {
""
};
(
format!("{mark}{}", script.name),
script
.path
.file_name()
.map(|p| p.to_string_lossy().into_owned())
.unwrap_or_default(),
true,
)
}
SettingsRow::VisualizationNew => {
("+ New visualization script".into(), "enter".into(), true)
}
SettingsRow::VisualizationEdit => {
("Edit selected visualization".into(), "enter".into(), true)
}
_ => continue,
};
let item = ListItem::new(format!("{label}: {value}"));
items.push(if enabled {
item
} else {
item.style(theme::dim())
});
}
frame.render_stateful_widget(
List::new(items)
.highlight_symbol("> ")
.highlight_style(theme::selection_for(state)),
list_area,
&mut ListState::default().with_selected(Some(selected)),
);
let message = state
.status_message
.as_deref()
.filter(|message| !message.is_empty())
.unwrap_or(&state.updater.message);
frame.render_widget(
Paragraph::new(message)
.wrap(Wrap { trim: true })
.style(theme::dim()),
status_area,
);
frame.render_widget(
Paragraph::new("Up/Down: navigate | Enter: select | Esc: back").style(theme::dim()),
footer,
);
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn window_renders_controls_and_scrolls_to_last_row_in_small_terminal() {
for (width, height) in [(80, 30), (45, 14)] {
let mut terminal =
ratatui::Terminal::new(ratatui::backend::TestBackend::new(width, height)).unwrap();
let mut state = AppState::default();
state.updater.message = "No newer stable release".into();
terminal.draw(|frame| draw(frame, &state)).unwrap();
let text: String = terminal
.backend()
.buffer()
.content
.iter()
.map(|c| c.symbol())
.collect();
assert!(text.contains("Additional settings"));
assert!(text.contains("Music save directory"));
if height >= 30 {
assert!(text.contains("Check for updates"));
assert!(text.contains("Install update"));
assert!(text.contains("Visualizations"));
}
state.additional_settings_cursor = additional_settings_rows(&state).len() - 1;
terminal.draw(|frame| draw(frame, &state)).unwrap();
let text: String = terminal
.backend()
.buffer()
.content
.iter()
.map(|c| c.symbol())
.collect();
assert!(text.contains("New visualization script"));
assert!(text.contains("No newer stable release"));
}
}
}
+1541
View File
File diff suppressed because it is too large. Load diff
+1036 -78
View File
File diff suppressed because it is too large. Load diff
-230
View File
@@ -1,230 +0,0 @@
use ratatui::Frame;
use ratatui::layout::{Alignment, Constraint, Flex, Layout, Rect};
use ratatui::style::{Color, Style};
use ratatui::text::{Line, Span};
use ratatui::widgets::{Block, Paragraph, Wrap};
use super::theme;
use crate::app::state::{LoginField, LoginForm, LoginMode};
pub fn draw(frame: &mut Frame, form: &LoginForm) {
match form.mode {
LoginMode::Form => draw_form(frame, form),
LoginMode::SsoPending => draw_sso_pending(frame, form),
}
}
fn draw_form(frame: &mut Frame, form: &LoginForm) {
let area = centered(frame.area(), 52, 19);
let block = Block::bordered()
.title(" Sign in to furumi ")
.title_style(theme::header())
.border_style(theme::accent());
let inner = block.inner(area);
frame.render_widget(block, area);
// SSO is the primary path: server URL + SSO button up top, the rarely
// used password fallback below a separator.
let [
server,
sso_button,
separator,
username,
password,
signin_button,
message,
hint,
] = Layout::vertical([
Constraint::Length(3),
Constraint::Length(1),
Constraint::Length(1),
Constraint::Length(3),
Constraint::Length(3),
Constraint::Length(1),
Constraint::Length(2),
Constraint::Length(1),
])
.areas(inner);
draw_field(
frame,
server,
"Server URL",
&form.server_url,
false,
form.focus == LoginField::ServerUrl,
);
draw_button(
frame,
sso_button,
"[ Continue with SSO ]",
form.focus == LoginField::SsoButton,
);
frame.render_widget(
Paragraph::new(Line::styled("── or sign in with password ──", theme::dim()))
.alignment(Alignment::Center),
separator,
);
draw_field(
frame,
username,
"Username",
&form.username,
false,
form.focus == LoginField::Username,
);
draw_field(
frame,
password,
"Password",
&form.password,
true,
form.focus == LoginField::Password,
);
draw_button(
frame,
signin_button,
"[ Sign in ]",
form.focus == LoginField::SignInButton,
);
draw_message(frame, message, form);
frame.render_widget(
Paragraph::new(Line::styled(
"tab/↑↓ move · enter submit · ctrl-c quit",
theme::dim(),
))
.alignment(Alignment::Center),
hint,
);
}
fn draw_sso_pending(frame: &mut Frame, form: &LoginForm) {
// The URL stays on ONE line (wrapping breaks copy-paste); the dialog is
// as wide as the terminal allows and ctrl-l copies the full link.
let width =
(form.sso_url.len() as u16 + 4).clamp(48, frame.area().width.saturating_sub(2).max(40));
let area = centered(frame.area(), width, 14.min(frame.area().height));
let block = Block::bordered()
.title(" Continue with SSO ")
.title_style(theme::header())
.border_style(theme::accent());
let inner = block.inner(area);
frame.render_widget(block, area);
let [steps, url_label, url, paste, message, hint] = Layout::vertical([
Constraint::Length(3),
Constraint::Length(1),
Constraint::Length(1),
Constraint::Length(3),
Constraint::Length(2),
Constraint::Length(1),
])
.areas(inner);
let lines = if let Some(port) = form.sso_port {
vec![
Line::raw("1. Finish signing in, in the browser window."),
Line::from(vec![
Span::raw("2. Sign-in completes here automatically "),
Span::styled(format!("(waiting on 127.0.0.1:{port})"), theme::dim()),
]),
Line::raw("3. If it doesn't, paste the code from the page below."),
]
} else {
vec![
Line::raw("1. Finish signing in, in the browser window."),
Line::raw("2. Copy the code shown on the final page."),
Line::raw("3. Paste it below and press Enter."),
]
};
frame.render_widget(Paragraph::new(lines), steps);
frame.render_widget(
Paragraph::new(Line::styled(
"If the browser didn't open — ctrl-l copies this link, ctrl-o retries:",
theme::dim(),
)),
url_label,
);
// One line, never wrapped: a wrapped URL copies with a line break and
// stops working. If it doesn't fit, ctrl-l still copies it whole.
frame.render_widget(
Paragraph::new(Line::styled(form.sso_url.clone(), theme::accent())),
url,
);
draw_field(frame, paste, "Link or code", &form.sso_paste, false, true);
draw_message(frame, message, form);
frame.render_widget(
Paragraph::new(Line::styled(
"enter submit · ctrl-l copy link · esc back · ctrl-c quit",
theme::dim(),
))
.alignment(Alignment::Center),
hint,
);
}
fn draw_field(frame: &mut Frame, area: Rect, label: &str, value: &str, mask: bool, focused: bool) {
let border = if focused {
theme::accent()
} else {
theme::dim()
};
let block = Block::bordered().title(label).border_style(border);
let shown = if mask {
"•".repeat(value.chars().count())
} else {
value.to_string()
};
// Keep the tail visible when the value overflows the field.
let width = block.inner(area).width.saturating_sub(1) as usize;
let mut text: String = shown
.chars()
.skip(shown.chars().count().saturating_sub(width))
.collect();
if focused {
text.push('█');
}
frame.render_widget(Paragraph::new(text).block(block), area);
}
fn draw_button(frame: &mut Frame, area: Rect, label: &str, focused: bool) {
let style = if focused {
theme::tab_active()
} else {
theme::dim()
};
frame.render_widget(
Paragraph::new(Line::styled(label, style)).alignment(Alignment::Center),
area,
);
}
fn draw_message(frame: &mut Frame, area: Rect, form: &LoginForm) {
let line = if form.busy {
Line::styled("signing in…", theme::accent())
} else if let Some(error) = &form.error {
Line::styled(error.clone(), Style::new().fg(Color::Red))
} else {
Line::default()
};
frame.render_widget(
Paragraph::new(line)
.wrap(Wrap { trim: true })
.alignment(Alignment::Center),
area,
);
}
fn centered(area: Rect, width: u16, height: u16) -> Rect {
let [rect] = Layout::horizontal([Constraint::Length(width.min(area.width))])
.flex(Flex::Center)
.areas(area);
let [rect] = Layout::vertical([Constraint::Length(height.min(area.height))])
.flex(Flex::Center)
.areas(rect);
rect
}
+9 -7
View File
@@ -14,8 +14,8 @@ pub fn draw(frame: &mut Frame, area: Rect, state: &AppState) {
let mode = if logs.follow { "follow" } else { "scroll" };
let block = Block::bordered()
.title(format!(" Logs — {level}+ · {mode} "))
.title_style(theme::header())
.border_style(theme::dim());
.title_style(theme::header_for(state))
.border_style(theme::border_for(state));
let inner = block.inner(area);
frame.render_widget(block, area);
@@ -39,13 +39,15 @@ pub fn draw(frame: &mut Frame, area: Rect, state: &AppState) {
};
let line = Line::from(vec![
Span::styled(format!("{} ", entry.time), theme::dim()),
level_span(entry.level),
level_span(entry.level, state),
Span::styled(format!(" {}: ", short_target(&entry.target)), theme::dim()),
Span::raw(entry.message.clone()),
]);
frame.render_widget(Paragraph::new(line), row);
if view.cursor_row == Some(row_index) {
frame.buffer_mut().set_style(row, theme::tab_active());
frame
.buffer_mut()
.set_style(row, theme::tab_active_for(state));
}
}
@@ -62,7 +64,7 @@ pub fn draw(frame: &mut Frame, area: Rect, state: &AppState) {
" ↑{} of {} · enter: details · shift-g: follow · v: level ",
view.from_end, view.matched
),
theme::tab_active(),
theme::tab_active_for(state),
))
.alignment(Alignment::Right),
footer,
@@ -85,14 +87,14 @@ fn centered(frame: &mut Frame, area: Rect, text: &str) {
);
}
fn level_span(level: tracing::Level) -> Span<'static> {
fn level_span(level: tracing::Level, state: &AppState) -> Span<'static> {
match level {
tracing::Level::ERROR => Span::styled(
"ERROR",
Style::new().fg(Color::Red).add_modifier(Modifier::BOLD),
),
tracing::Level::WARN => Span::styled("WARN ", Style::new().fg(Color::Yellow)),
tracing::Level::INFO => Span::styled("INFO ", theme::accent()),
tracing::Level::INFO => Span::styled("INFO ", theme::accent_for(state)),
tracing::Level::DEBUG => Span::styled("DEBUG", theme::dim()),
tracing::Level::TRACE => Span::styled("TRACE", theme::dim()),
}
+929 -133
View File
File diff suppressed because it is too large. Load diff
+33 -37
View File
@@ -4,8 +4,8 @@ use ratatui::style::{Color, Style};
use ratatui::text::{Line, Span};
use ratatui::widgets::{Block, Paragraph};
use super::{theme, track_row};
use crate::app::state::{AppState, Loadable, TrackSelectionScope};
use super::{loading_line, theme, track_row_with_like_marker};
use crate::app::state::{AppState, LIKES_PLAYLIST_ID, Loadable, TrackSelectionScope};
use crate::app::update::playlist_tracks;
pub fn draw(frame: &mut Frame, area: Rect, state: &AppState) {
@@ -15,11 +15,11 @@ pub fn draw(frame: &mut Frame, area: Rect, state: &AppState) {
}
}
fn bordered(frame: &mut Frame, area: Rect, title: String) -> Rect {
fn bordered(frame: &mut Frame, area: Rect, state: &AppState, title: String) -> Rect {
let block = Block::bordered()
.title(title)
.title_style(theme::header())
.border_style(theme::dim());
.title_style(theme::header_for(state))
.border_style(theme::border_for(state));
let inner = block.inner(area);
frame.render_widget(block, area);
inner
@@ -38,7 +38,15 @@ fn centered_line(frame: &mut Frame, area: Rect, line: Line) {
}
fn draw_list(frame: &mut Frame, area: Rect, state: &AppState) {
let inner = bordered(frame, area, " Playlists ".to_string());
let inner = bordered(
frame,
area,
state,
format!(
" Playlists · Mode: {} ",
state.global.filters.source_mode.label()
),
);
let selected = state.playlists.selected;
let list = match &state.playlists.list {
@@ -51,11 +59,7 @@ fn draw_list(frame: &mut Frame, area: Rect, state: &AppState) {
);
}
_ => {
return centered_line(
frame,
inner,
Line::styled("loading playlists…", theme::dim()),
);
return centered_line(frame, inner, loading_line(state, "loading playlists…"));
}
};
if list.is_empty() {
@@ -74,30 +78,12 @@ fn draw_list(frame: &mut Frame, area: Rect, state: &AppState) {
height: 1,
};
let marker = if playlist.kind == "likes" {
Span::styled("♥ ", theme::accent())
Span::styled("♥ ", theme::accent_for(state))
} else {
Span::raw(" ")
};
let mut flags = Vec::new();
if !playlist.is_own {
if let Some(owner) = &playlist.owner_name {
flags.push(format!("by {owner}"));
}
}
if playlist.is_public {
flags.push("public".to_string());
}
let suffix = if flags.is_empty() {
String::new()
} else {
format!(" {}", flags.join(" · "))
};
frame.render_widget(
Paragraph::new(Line::from(vec![
marker,
Span::raw(playlist.title.clone()),
Span::styled(suffix, theme::dim()),
])),
Paragraph::new(Line::from(vec![marker, Span::raw(playlist.title.clone())])),
row,
);
frame.render_widget(
@@ -109,7 +95,9 @@ fn draw_list(frame: &mut Frame, area: Rect, state: &AppState) {
row,
);
if index == selected {
frame.buffer_mut().set_style(row, theme::tab_active());
frame
.buffer_mut()
.set_style(row, theme::tab_active_for(state));
}
}
}
@@ -117,10 +105,17 @@ fn draw_list(frame: &mut Frame, area: Rect, state: &AppState) {
fn draw_opened(frame: &mut Frame, area: Rect, state: &AppState, id: i64, cursor: usize) {
let loadable = state.playlist_views.get(&id);
let title = match loadable {
Some(Loadable::Ready(detail)) => format!(" Playlists ▸ {} ", detail.title),
_ => " Playlists ▸ … ".to_string(),
Some(Loadable::Ready(detail)) => format!(
" Playlists ▸ {} · Mode: {} ",
detail.title,
state.global.filters.source_mode.label()
),
_ => format!(
" Playlists ▸ … · Mode: {} ",
state.global.filters.source_mode.label()
),
};
let inner = bordered(frame, area, title);
let inner = bordered(frame, area, state, title);
if let Some(Loadable::Failed(error)) = loadable {
return centered_line(
@@ -130,7 +125,7 @@ fn draw_opened(frame: &mut Frame, area: Rect, state: &AppState, id: i64, cursor:
);
}
let Some(tracks) = playlist_tracks(state, id) else {
return centered_line(frame, inner, Line::styled("loading…", theme::dim()));
return centered_line(frame, inner, loading_line(state, "loading…"));
};
if tracks.is_empty() {
return centered_line(
@@ -151,7 +146,7 @@ fn draw_opened(frame: &mut Frame, area: Rect, state: &AppState, id: i64, cursor:
width: inner.width,
height: 1,
};
track_row(
track_row_with_like_marker(
frame,
row,
state,
@@ -161,6 +156,7 @@ fn draw_opened(frame: &mut Frame, area: Rect, state: &AppState, id: i64, cursor:
state
.track_selection
.contains(&TrackSelectionScope::Playlist(id), index),
id != LIKES_PLAYLIST_ID,
);
}
}
+284
View File
@@ -0,0 +1,284 @@
//! The public podcast card opened from the search results. In Russian, like
//! the share confirmation: «Подписаться» / «Уже подписан» are the actions
//! the requirements name.
//!
//! Everything but the origin feed URL is a publisher's claim and is shown as
//! such; the episode preview comes from the feed itself.
use ratatui::Frame;
use ratatui::layout::{Alignment, Constraint, Layout};
use ratatui::style::{Color, Modifier, Style};
use ratatui::text::{Line, Span};
use ratatui::widgets::{Block, Clear, Paragraph, Wrap};
use super::podcasts::{format_date, format_duration_ms};
use super::popup::centered;
use super::theme;
use crate::app::state::{AppState, Loadable};
use crate::podcasts::discovery::{FeedPreview, PodcastHit};
pub(super) fn draw(
frame: &mut Frame,
state: &AppState,
hit: &PodcastHit,
preview: Option<&Loadable<FeedPreview>>,
scroll: u16,
max_scroll: &std::cell::Cell<u16>,
) {
let subscribed =
crate::app::update::podcast_discovery::subscribed_id(state, hit, preview).is_some();
let subscribing = state.podcasts.subscribing;
let lines = card_lines(state, hit, preview, subscribed, subscribing);
let width = 92.min(frame.area().width.saturating_sub(4)).max(30);
let inner_width = width.saturating_sub(2).max(1);
let paragraph = Paragraph::new(lines).wrap(Wrap { trim: false });
// The height of the word-wrapped text, as it is rendered.
let body_height = u16::try_from(paragraph.line_count(inner_width)).unwrap_or(u16::MAX);
let height = body_height
.saturating_add(4)
.min(frame.area().height.saturating_sub(2));
let area = centered(frame.area(), width, height);
let block = Block::bordered()
.title(" Подкаст · публичная карточка ")
.title_style(theme::header_for(state))
.border_style(theme::strong_border_for(state));
let inner = block.inner(area);
frame.render_widget(Clear, area);
frame.render_widget(block, area);
let [body, footer_area] =
Layout::vertical([Constraint::Min(1), Constraint::Length(1)]).areas(inner);
let last = body_height.saturating_sub(body.height);
max_scroll.set(last);
frame.render_widget(paragraph.scroll((scroll.min(last), 0)), body);
let footer = if subscribed {
"enter открыть · e выпуски · ↑↓ прокрутка · esc закрыть"
} else {
"enter подписаться · e выпуски · ↑↓ прокрутка · esc закрыть"
};
frame.render_widget(
Paragraph::new(Line::styled(footer, theme::dim())).alignment(Alignment::Center),
footer_area,
);
}
fn card_lines(
state: &AppState,
hit: &PodcastHit,
preview: Option<&Loadable<FeedPreview>>,
subscribed: bool,
subscribing: bool,
) -> Vec<Line<'static>> {
let card = &hit.hit.card;
let bold = Style::new().add_modifier(Modifier::BOLD);
let mut lines = vec![
Line::from(vec![
Span::styled("[podcast] ", theme::accent_for(state)),
Span::styled(card.title.clone(), bold),
]),
Line::styled(
"Сведения ниже указали издатели карточки; они не проверены.",
theme::dim(),
),
Line::raw(""),
];
if let Some(author) = &card.author {
lines.push(field("Автор", author.clone()));
}
if !card.categories.is_empty() {
lines.push(field("Категории", card.categories.join(", ")));
}
if let Some(language) = &card.language {
lines.push(field("Язык", language.clone()));
}
let mut episodes = match card.episode_count {
Some(count) => format!("{count}"),
None => "не указано".to_string(),
};
if let Some(latest) = card.latest_episode_at_ms {
episodes.push_str(&format!(
" · последний {}",
format_date(latest.div_euclid(1000))
));
}
lines.push(field("Выпусков", episodes));
let publishers = hit.hit.publishers.len();
lines.push(field(
"Опубликовали",
format!(
"{publishers} {} (не число подписчиков и не знак доверия)",
plural_ru(publishers, "устройство", "устройства", "устройств")
),
));
lines.push(field("Лента", hit.hit.feed_url.as_str().to_string()));
for claim in &hit.hit.claimed_feed_urls {
lines.push(Line::styled(
format!(
"Заявленный новый адрес (не проверен, не используется): {}",
claim.feed_url.as_str()
),
theme::dim(),
));
}
if let Some(link) = &card.link {
lines.push(field("Сайт", link.clone()));
}
if let Some(description) = &card.description {
lines.push(Line::raw(""));
lines.extend(
description
.lines()
.map(|line| Line::raw(line.replace('\t', " "))),
);
}
lines.push(Line::raw(""));
if subscribed {
lines.push(Line::from(vec![
Span::styled(
"✓ Уже подписан",
Style::new().fg(Color::Green).add_modifier(Modifier::BOLD),
),
Span::styled(
" · enter откроет подкаст во вкладке Podcasts",
theme::dim(),
),
]));
} else if subscribing {
lines.push(Line::styled(
"Подписка… читаем ленту",
theme::accent_for(state),
));
} else {
lines.push(Line::from(vec![
Span::styled(
"[ Подписаться ]",
theme::accent_for(state).add_modifier(Modifier::BOLD),
),
Span::styled(
" лента будет прочитана с её сервера; подписка личная и не публикуется",
theme::dim(),
),
]));
}
lines.push(Line::raw(""));
lines.push(Line::styled(
"Сезоны и выпуски (из RSS-ленты)",
theme::header_for(state),
));
match preview {
None => lines.push(Line::styled(
"e — прочитать ленту без подписки (запрос к серверу ленты)",
theme::dim(),
)),
Some(Loadable::Loading) => {
lines.push(Line::styled("читаем ленту…", theme::accent_for(state)))
}
Some(Loadable::Failed(err)) => lines.push(Line::styled(
format!("не удалось прочитать ленту: {err}"),
Style::new().fg(Color::Red),
)),
Some(Loadable::Ready(feed)) => preview_lines(&mut lines, card.title.as_str(), feed),
}
lines
}
fn preview_lines(lines: &mut Vec<Line<'static>>, card_title: &str, feed: &FeedPreview) {
if feed.title != card_title {
lines.push(field("Название в ленте", feed.title.clone()));
}
if let Some(moved) = &feed.moved_to {
lines.push(field("Лента переехала", moved.as_str().to_string()));
}
let seasons: Vec<String> = feed
.seasons
.iter()
.map(|(season, count)| match season {
Some(season) => format!("сезон {season}: {count}"),
None => format!("без сезона: {count}"),
})
.collect();
lines.push(field(
"В ленте",
format!(
"{} {}{}",
feed.episode_count,
plural_ru(feed.episode_count, "выпуск", "выпуска", "выпусков"),
if seasons.is_empty() {
String::new()
} else {
format!(" · {}", seasons.join(", "))
}
),
));
for episode in &feed.episodes {
let mut meta = Vec::new();
match (episode.season, episode.episode_number) {
(Some(season), Some(number)) => meta.push(format!("S{season}E{number}")),
(Some(season), None) => meta.push(format!("S{season}")),
(None, Some(number)) => meta.push(format!("#{number}")),
(None, None) => {}
}
if let Some(published) = episode.published_at_ms {
meta.push(format_date(published.div_euclid(1000)));
}
if let Some(duration) = episode.duration_ms {
meta.push(format_duration_ms(duration));
}
lines.push(Line::from(vec![
Span::raw(format!("• {}", episode.title)),
Span::styled(
if meta.is_empty() {
String::new()
} else {
format!(" {}", meta.join(" · "))
},
theme::dim(),
),
]));
}
if feed.episodes.len() < feed.episode_count {
lines.push(Line::styled(
format!("… и ещё {}", feed.episode_count - feed.episodes.len()),
theme::dim(),
));
}
}
fn field(label: &str, value: String) -> Line<'static> {
Line::from(vec![
Span::styled(format!("{label}: "), theme::dim()),
Span::raw(value),
])
}
/// Russian plural form for `n`.
fn plural_ru(n: usize, one: &'static str, few: &'static str, many: &'static str) -> &'static str {
let (tens, units) = (n % 100, n % 10);
if (11..=14).contains(&tens) {
many
} else if units == 1 {
one
} else if (2..=4).contains(&units) {
few
} else {
many
}
}
#[cfg(test)]
mod tests {
use super::plural_ru;
#[test]
fn russian_plurals() {
let forms = |n| plural_ru(n, "устройство", "устройства", "устройств");
assert_eq!(forms(1), "устройство");
assert_eq!(forms(3), "устройства");
assert_eq!(forms(5), "устройств");
assert_eq!(forms(11), "устройств");
assert_eq!(forms(21), "устройство");
assert_eq!(forms(0), "устройств");
}
}
+828
View File
@@ -0,0 +1,828 @@
//! Podcasts tab: subscriptions with their check status, a podcast's
//! seasons, and its episodes with saved position, played state, duration
//! and date. Rendering only reads `AppState`.
use furumi_library::podcasts::{EpisodeListItem, SeasonSummary};
use music_dht::podcast::ProgressStatus;
use ratatui::Frame;
use ratatui::layout::{Alignment, Constraint, Layout, Rect};
use ratatui::style::{Color, Modifier, Style};
use ratatui::text::{Line, Span};
use ratatui::widgets::{Block, Borders, Paragraph, Wrap};
use unicode_width::UnicodeWidthStr;
use super::{loading_line, theme};
use crate::app::state::{
ART_HEADER_HEIGHT, ART_HEADER_WIDTH, AppState, ArtState, Loadable, PodcastListRow, PodcastRow,
PodcastStoreStatus, SeasonRow,
};
use crate::app::update::podcasts::{played_label, sort_label};
use crate::podcasts::publication::{Discovery, Publication};
/// Width below which the side panel with the cover is dropped.
const SIDE_PANEL_MIN_TOTAL_WIDTH: u16 = 80;
const SIDE_PANEL_WIDTH: u16 = ART_HEADER_WIDTH + 2;
pub(crate) const EMPTY_HINT: &str =
"No subscriptions yet. Choose \"Add podcast\" and paste an RSS feed URL.";
pub(crate) const STORE_FAILED_NOTE: &str = "The podcast database was left unchanged. \
Music, playlists and sync keep working.";
pub fn draw(frame: &mut Frame, area: Rect, state: &AppState) {
let tab = &state.podcasts;
match &tab.store {
PodcastStoreStatus::Opening => {
let inner = bordered(frame, area, state, " Podcasts ".into());
return centered_line(
frame,
inner,
loading_line(state, "opening the podcast database…"),
);
}
PodcastStoreStatus::Failed(err) => {
let inner = bordered(frame, area, state, " Podcasts ".into());
let lines = vec![
Line::styled("Podcasts are unavailable", theme::header_for(state)),
Line::default(),
Line::styled(err.clone(), error_style()),
Line::default(),
Line::styled(STORE_FAILED_NOTE, theme::dim()),
];
frame.render_widget(
Paragraph::new(lines)
.alignment(Alignment::Center)
.wrap(Wrap { trim: true }),
inner,
);
return;
}
PodcastStoreStatus::Ready => {}
}
match &tab.opened {
None => draw_list(frame, area, state),
Some(opened) if opened.season.is_none() => draw_seasons(frame, area, state),
Some(_) => draw_episodes(frame, area, state),
}
}
fn bordered(frame: &mut Frame, area: Rect, state: &AppState, title: String) -> Rect {
let block = Block::bordered()
.title(title)
.title_style(theme::header_for(state))
.border_style(theme::border_for(state));
let inner = block.inner(area);
frame.render_widget(block, area);
inner
}
fn centered_line(frame: &mut Frame, area: Rect, line: Line) {
if area.height == 0 {
return;
}
let middle = Rect {
y: area.y + area.height / 2,
height: 1,
..area
};
frame.render_widget(Paragraph::new(line).alignment(Alignment::Center), middle);
}
fn error_style() -> Style {
Style::new().fg(Color::Red)
}
/// First row so that `cursor` stays visible, roughly centered.
fn first_visible(cursor: usize, len: usize, visible: usize) -> usize {
cursor
.saturating_sub(visible / 2)
.min(len.saturating_sub(visible))
}
fn row_area(area: Rect, offset: usize) -> Rect {
Rect {
y: area.y + offset as u16,
height: 1,
..area
}
}
/// A row with a left part and a right-aligned dim part.
fn draw_row(
frame: &mut Frame,
area: Rect,
state: &AppState,
left: Line<'static>,
right: Option<String>,
selected: bool,
) {
frame.render_widget(Paragraph::new(left), area);
if let Some(right) = right {
frame.render_widget(
Paragraph::new(Line::styled(format!("{right} "), theme::dim()))
.alignment(Alignment::Right),
area,
);
}
if selected {
frame
.buffer_mut()
.set_style(area, theme::tab_active_for(state));
}
}
// ---------------------------------------------------------------------------
// Subscriptions
fn draw_list(frame: &mut Frame, area: Rect, state: &AppState) {
let tab = &state.podcasts;
let inner = bordered(frame, area, state, " Podcasts ".to_string());
match &tab.list {
Some(Loadable::Failed(error)) => {
return centered_line(frame, inner, Line::styled(error.clone(), error_style()));
}
None | Some(Loadable::Loading) => {
return centered_line(frame, inner, loading_line(state, "loading podcasts…"));
}
Some(Loadable::Ready(_)) => {}
}
let (list_area, side_area) = split_side_panel(inner);
if let Some(side) = side_area {
draw_side_panel(frame, side, state, tab.current_podcast());
}
let rows = tab.list_rows();
let visible = usize::from(list_area.height.max(1));
let first = first_visible(tab.selected, rows.len(), visible);
for (index, row) in rows.iter().enumerate().skip(first).take(visible) {
let (left, right) = list_row(state, *row, list_area.width);
draw_row(
frame,
row_area(list_area, index - first),
state,
left,
right,
index == tab.selected,
);
}
let used = rows.len().saturating_sub(first).min(visible) as u16;
let below = Rect {
y: list_area.y + used + 1,
height: list_area.height.saturating_sub(used + 1),
..list_area
};
if below.height == 0 {
return;
}
let hint = if tab.podcasts().is_empty() {
Line::styled(EMPTY_HINT, theme::dim())
} else if side_area.is_none()
&& let Some(row) = tab.current_podcast()
{
// Narrow terminal: the selected podcast's status below the list.
fetch_status_line(state, row)
} else {
Line::default()
};
frame.render_widget(Paragraph::new(hint).wrap(Wrap { trim: true }), below);
}
fn list_row(state: &AppState, row: PodcastListRow, width: u16) -> (Line<'static>, Option<String>) {
let tab = &state.podcasts;
match row {
PodcastListRow::Add => {
let label = if tab.subscribing {
format!("{} Adding podcast…", state.spinner())
} else {
"+ Add podcast (RSS feed URL)…".to_string()
};
(Line::styled(label, theme::accent_for(state)), None)
}
PodcastListRow::RefreshAll => {
let label = if tab.refreshing.is_empty() {
"↻ Check all podcasts for new episodes".to_string()
} else {
format!(
"{} Checking {} feed(s) for new episodes…",
state.spinner(),
tab.refreshing.len()
)
};
(Line::styled(label, theme::accent_for(state)), None)
}
PodcastListRow::Podcast(index) => {
let Some(podcast) = tab.podcasts().get(index) else {
return (Line::raw(""), None);
};
let marker = if tab.refreshing.contains(podcast.id()) {
Span::styled(format!("{} ", state.spinner()), theme::accent_for(state))
} else if podcast.fetch.last_error.is_some() {
Span::styled("! ", error_style())
} else {
Span::raw(" ")
};
let summary = &podcast.summary;
let mut meta = if summary.unplayed_count > 0 {
format!(
"{} unplayed · {} ep",
summary.unplayed_count, summary.episode_count
)
} else {
format!("{} ep", summary.episode_count)
};
if summary.shared {
meta = format!("shared · {meta}");
}
let title_width = usize::from(width).saturating_sub(2 + meta.width() + 2);
let left = Line::from(vec![
marker,
Span::raw(fit_width(podcast.title(), title_width)),
]);
(left, Some(meta))
}
}
}
/// Main area plus an optional right-hand panel for the cover and details.
fn split_side_panel(area: Rect) -> (Rect, Option<Rect>) {
if area.width < SIDE_PANEL_MIN_TOTAL_WIDTH {
return (area, None);
}
let [main, side] =
Layout::horizontal([Constraint::Min(0), Constraint::Length(SIDE_PANEL_WIDTH)]).areas(area);
(main, Some(side))
}
fn draw_side_panel(frame: &mut Frame, area: Rect, state: &AppState, podcast: Option<&PodcastRow>) {
let block = Block::default()
.borders(Borders::LEFT)
.border_style(theme::border_for(state));
let inner = block.inner(area);
frame.render_widget(block, area);
let Some(podcast) = podcast else {
return;
};
let inner = Rect {
x: inner.x + 1,
width: inner.width.saturating_sub(1),
..inner
};
let art_height = ART_HEADER_HEIGHT.min(inner.height);
draw_cover(
frame,
Rect {
height: art_height,
width: ART_HEADER_WIDTH.min(inner.width),
..inner
},
state,
podcast,
);
let text_area = Rect {
y: inner.y + art_height + 1,
height: inner.height.saturating_sub(art_height + 1),
..inner
};
if text_area.height == 0 {
return;
}
let summary = &podcast.summary;
let mut lines = vec![Line::styled(
podcast.title().to_string(),
Style::new().add_modifier(Modifier::BOLD),
)];
if let Some(author) = &summary.meta.author {
lines.push(Line::styled(author.clone(), theme::dim()));
}
let mut counts = format!("{} episodes", summary.episode_count);
if summary.season_count > 0 {
counts.push_str(&format!(" · {} seasons", summary.season_count));
}
lines.push(Line::styled(counts, theme::dim()));
lines.push(share_status_line(state, podcast));
lines.push(fetch_status_line(state, podcast));
if let Some(description) = &summary.meta.description {
lines.push(Line::raw(""));
lines.push(Line::raw(description.clone()));
}
frame.render_widget(Paragraph::new(lines).wrap(Wrap { trim: true }), text_area);
}
/// Public discovery state of one podcast: private, or shared and whether
/// this device publishes its card.
pub(crate) fn share_status_line(state: &AppState, podcast: &PodcastRow) -> Line<'static> {
let tab = &state.podcasts;
if tab.share_busy.contains(podcast.id()) {
return loading_line(state, "saving the share setting…");
}
let report = &tab.publication;
// A card from this device that is still live although the podcast is
// private now (revocation pending, failed, or federation off).
let unrevoked = report.unrevoked.contains(podcast.id());
if !podcast.summary.shared || (unrevoked && !report.podcasts.contains_key(podcast.id())) {
if !unrevoked {
return Line::styled("private (not shared in the federation)", theme::dim());
}
if let Discovery::Off(_) = report.discovery {
return Line::styled(
"private · public card may not be revoked yet: federation is off",
Style::new().fg(Color::Yellow),
);
}
return loading_line(
state,
"private · revoking the public card from this device…",
);
}
let (text, style) = match (&report.discovery, report.podcasts.get(podcast.id())) {
(Discovery::Off(reason), _) => (format!("shared · not published: {reason}"), theme::dim()),
(_, Some(Publication::HeldBack(_))) => (
"shared · held back on this device: the feed URL looks private, \
press Shift+F to confirm"
.to_string(),
Style::new().fg(Color::Yellow),
),
(_, Some(Publication::Failed(error))) => {
(format!("shared · not published: {error}"), error_style())
}
(Discovery::Running { peers: 0 }, Some(Publication::Published)) => (
"shared · published from this device (no discovery peers yet)".to_string(),
theme::accent_for(state),
),
(_, Some(Publication::Published)) => (
"shared · published from this device".to_string(),
theme::accent_for(state),
),
(_, Some(Publication::WaitingForDevices)) => (
"shared · not published yet: waiting for a sync with your other devices".to_string(),
theme::dim(),
),
(Discovery::Starting, _) | (_, Some(Publication::Pending) | None) => {
return loading_line(state, "shared · publishing…");
}
};
Line::styled(text, style)
}
/// Refresh status of one podcast: checking, the last error, or when it was
/// last checked.
fn fetch_status_line(state: &AppState, podcast: &PodcastRow) -> Line<'static> {
if state.podcasts.refreshing.contains(podcast.id()) {
return loading_line(state, "checking for new episodes…");
}
let fetch = &podcast.fetch;
if let Some(error) = &fetch.last_error {
let mut text = format!("last check failed: {error}");
if fetch.consecutive_failures > 1 {
text.push_str(&format!(" ({} times)", fetch.consecutive_failures));
}
if let Some(next) = fetch.next_check_at_ms {
text.push_str(&format!("; next try {}", relative_time(next)));
}
return Line::styled(text, error_style());
}
match fetch.last_success_at_ms {
Some(at) => Line::styled(format!("checked {}", relative_time(at)), theme::dim()),
None => Line::styled("not checked yet", theme::dim()),
}
}
fn draw_cover(frame: &mut Frame, area: Rect, state: &AppState, podcast: &PodcastRow) {
let art = podcast.fetch.cover_path.as_ref().and_then(|path| {
state.art.get(&crate::art::cache_key(
path,
ART_HEADER_WIDTH,
ART_HEADER_HEIGHT,
))
});
match art {
Some(ArtState::Ready(image)) => {
frame.render_widget(Paragraph::new(super::art::to_text(image)), area);
}
Some(ArtState::Loading) => centered_line(frame, area, Line::styled("…", theme::dim())),
_ => centered_line(frame, area, Line::styled("🎙", theme::dim())),
}
}
// ---------------------------------------------------------------------------
// Seasons
fn draw_seasons(frame: &mut Frame, area: Rect, state: &AppState) {
let tab = &state.podcasts;
let podcast = tab.current_podcast();
let title = podcast.map_or("…".to_string(), |row| row.title().to_string());
let inner = bordered(frame, area, state, format!(" Podcasts ▸ {title} "));
let seasons = match &tab.seasons {
Some((_, Loadable::Failed(error))) => {
return centered_line(frame, inner, Line::styled(error.clone(), error_style()));
}
_ => match tab.opened_seasons() {
Some(seasons) => seasons,
None => return centered_line(frame, inner, loading_line(state, "loading seasons…")),
},
};
let (main, side) = split_side_panel(inner);
if let Some(side) = side {
draw_side_panel(frame, side, state, podcast);
}
let cursor = tab
.opened
.as_ref()
.and_then(|opened| opened.season_cursor)
.unwrap_or(0);
let rows = tab.season_rows();
let visible = usize::from(main.height.max(1));
let first = first_visible(cursor, rows.len(), visible);
for (index, row) in rows.iter().enumerate().skip(first).take(visible) {
let (label, meta) = match row {
SeasonRow::All => {
let (episodes, unplayed) = seasons.iter().fold((0, 0), |(e, u), season| {
(e + season.episode_count, u + season.unplayed_count)
});
("All episodes".to_string(), counts(episodes, unplayed))
}
SeasonRow::Group(index) => {
let Some(season) = seasons.get(*index) else {
continue;
};
(season_title(season), season_meta(season))
}
};
let width = usize::from(main.width).saturating_sub(meta.width() + 4);
draw_row(
frame,
row_area(main, index - first),
state,
Line::raw(format!(" {}", fit_width(&label, width))),
Some(meta),
index == cursor,
);
}
}
fn season_title(season: &SeasonSummary) -> String {
match season.season {
Some(number) => format!("Season {number}"),
None => "Without a season".to_string(),
}
}
fn counts(episodes: u64, unplayed: u64) -> String {
if unplayed > 0 {
format!("{unplayed} unplayed · {episodes} ep")
} else {
format!("{episodes} ep")
}
}
fn season_meta(season: &SeasonSummary) -> String {
let mut meta = counts(season.episode_count, season.unplayed_count);
let years = (
season.first_published_at_ms.map(year_of),
season.last_published_at_ms.map(year_of),
);
match years {
(Some(first), Some(last)) if first != last => meta.push_str(&format!(" · {first}–{last}")),
(Some(year), _) | (None, Some(year)) => meta.push_str(&format!(" · {year}")),
(None, None) => {}
}
meta
}
// ---------------------------------------------------------------------------
// Episodes
fn draw_episodes(frame: &mut Frame, area: Rect, state: &AppState) {
let tab = &state.podcasts;
let Some(opened) = &tab.opened else {
return;
};
let podcast = tab.current_podcast();
let mut title = podcast.map_or("…".to_string(), |row| row.title().to_string());
if opened.season_cursor.is_some() {
let season = match opened.season {
Some(furumi_library::podcasts::SeasonFilter::Season(number)) => {
format!("Season {number}")
}
Some(furumi_library::podcasts::SeasonFilter::NoSeason) => {
"Without a season".to_string()
}
_ => "All episodes".to_string(),
};
title = format!("{title} ▸ {season}");
}
let inner = bordered(frame, area, state, format!(" Podcasts ▸ {title} "));
let Some(list) = tab.opened_episodes() else {
return centered_line(frame, inner, loading_line(state, "loading episodes…"));
};
let (main, side) = split_side_panel(inner);
if let Some(side) = side {
draw_side_panel(frame, side, state, podcast);
}
let notes_height = if main.height >= 18 { 6 } else { 0 };
let [summary_area, list_area, notes_area] = Layout::vertical([
Constraint::Length(1),
Constraint::Min(1),
Constraint::Length(notes_height),
])
.areas(main);
let mut summary = vec![Span::styled(
episode_summary(state, list.items.len(), list.complete),
theme::dim(),
)];
if list.loading || list.loading_more {
summary.push(Span::raw(" "));
summary.extend(loading_line(state, "loading…").spans);
} else if podcast.is_some_and(|row| tab.refreshing.contains(row.id())) {
summary.push(Span::raw(" "));
summary.extend(loading_line(state, "checking for new episodes…").spans);
}
frame.render_widget(Paragraph::new(Line::from(summary)), summary_area);
if let Some(error) = &list.error {
return centered_line(frame, list_area, Line::styled(error.clone(), error_style()));
}
if list.items.is_empty() {
if list.loading {
return;
}
let message = if tab.search.trim().is_empty()
&& tab.played == furumi_library::podcasts::PlayedFilter::Any
{
"this feed has no playable episodes yet"
} else {
"no episode matches the search or filter"
};
return centered_line(frame, list_area, Line::styled(message, theme::dim()));
}
let cursor = opened.episode_cursor.min(list.items.len() - 1);
let visible = usize::from(list_area.height.max(1));
let first = first_visible(cursor, list.items.len(), visible);
for (index, item) in list.items.iter().enumerate().skip(first).take(visible) {
draw_episode_row(
frame,
row_area(list_area, index - first),
state,
item,
index == cursor,
);
}
if notes_height > 0
&& let Some(item) = list.items.get(cursor)
{
draw_notes(frame, notes_area, state, item);
}
}
fn episode_summary(state: &AppState, loaded: usize, complete: bool) -> String {
let tab = &state.podcasts;
let count = if complete {
format!("{loaded} episodes")
} else {
format!("{loaded}+ episodes")
};
let mut parts = vec![
count,
played_label(tab.played).to_string(),
sort_label(tab.sort).to_string(),
];
let search = tab.search.trim();
if !search.is_empty() {
parts.push(format!("search: \"{search}\""));
}
parts.join(" · ")
}
/// Marker and right-hand text for an episode's listening state.
pub(crate) fn episode_state(item: &EpisodeListItem) -> (&'static str, String) {
let duration = item.episode.duration_ms.filter(|ms| *ms > 0);
match item.status() {
ProgressStatus::Completed => (
"✓",
match duration {
Some(ms) => format!("played · {}", format_duration_ms(ms)),
None => "played".to_string(),
},
),
ProgressStatus::InProgress => {
let position = format_duration_ms(item.resume_position_ms());
(
"◐",
match duration {
Some(ms) => format!("{position} / {}", format_duration_ms(ms)),
None => format!("at {position}"),
},
)
}
ProgressStatus::NotStarted => ("●", duration.map(format_duration_ms).unwrap_or_default()),
}
}
fn draw_episode_row(
frame: &mut Frame,
area: Rect,
state: &AppState,
item: &EpisodeListItem,
selected: bool,
) {
let episode = &item.episode;
let date = episode
.published_at_ms
.map(|ms| format_date(ms.div_euclid(1000)))
.unwrap_or_else(|| " ".repeat(10));
let (mut marker, mut right) = episode_state(item);
let mut marker_style = match item.status() {
ProgressStatus::NotStarted => theme::accent_for(state),
_ => theme::dim(),
};
// The episode playing on this device shows its live position.
if let Some(position_ms) = playing_position_ms(state, &episode.episode_id) {
marker = "▶";
marker_style = theme::accent_for(state);
let position = format_duration_ms(position_ms);
right = match episode.duration_ms.filter(|ms| *ms > 0) {
Some(ms) => format!("{position} / {}", format_duration_ms(ms)),
None => position,
};
}
let number = match (episode.season, episode.episode_number) {
(Some(season), Some(number)) => format!("S{season}E{number} "),
(None, Some(number)) => format!("#{number} "),
_ => String::new(),
};
let mut title = episode.title.clone();
if !item.in_feed {
title.push_str(" (no longer in the feed)");
}
let title_width =
usize::from(area.width).saturating_sub(2 + 10 + 2 + number.width() + right.width() + 2);
let title_style = match item.status() {
ProgressStatus::Completed => theme::dim(),
_ => Style::default(),
};
let line = Line::from(vec![
Span::styled(format!("{marker} "), marker_style),
Span::styled(date, theme::dim()),
Span::raw(" "),
Span::styled(number, theme::dim()),
Span::styled(fit_width(&title, title_width), title_style),
]);
draw_row(
frame,
area,
state,
line,
(!right.is_empty()).then_some(right),
selected,
);
}
/// Position of `episode_id` when it is the item playing (or paused) here.
fn playing_position_ms(
state: &AppState,
episode_id: &music_dht::podcast::EpisodeId,
) -> Option<i64> {
let player = &state.player;
let current = player.current.as_ref()?.podcast_episode_ref()?;
(player.playing && current.episode_id == *episode_id)
.then(|| (player.position_secs.max(0.0) * 1_000.0).round() as i64)
}
fn draw_notes(frame: &mut Frame, area: Rect, state: &AppState, item: &EpisodeListItem) {
let block = Block::default()
.borders(Borders::TOP)
.border_style(theme::border_for(state))
.title(Span::styled(" Episode notes ", theme::dim()));
let inner = block.inner(area);
frame.render_widget(block, area);
let mut text = item
.episode
.description
.clone()
.unwrap_or_else(|| "No description in the feed.".to_string());
if item.completed_count > 1 {
text = format!("Listened {} times. {text}", item.completed_count);
}
frame.render_widget(
Paragraph::new(Line::raw(text)).wrap(Wrap { trim: true }),
inner,
);
}
// ---------------------------------------------------------------------------
// Formatting
/// Truncate to a display width, adding an ellipsis when cut.
pub(crate) fn fit_width(text: &str, width: usize) -> String {
if UnicodeWidthStr::width(text) <= width {
return text.to_string();
}
if width == 0 {
return String::new();
}
let mut out = String::new();
let mut used = 0;
for ch in text.chars() {
let w = unicode_width::UnicodeWidthChar::width(ch).unwrap_or(0);
if used + w + 1 > width {
break;
}
out.push(ch);
used += w;
}
out.push('…');
out
}
pub(crate) fn format_duration_ms(ms: i64) -> String {
let total = (ms.max(0) + 500) / 1000;
let (hours, minutes, secs) = (total / 3600, total / 60 % 60, total % 60);
if hours > 0 {
format!("{hours}:{minutes:02}:{secs:02}")
} else {
format!("{minutes}:{secs:02}")
}
}
/// `YYYY-MM-DD` (UTC) for unix seconds: Howard Hinnant's days-to-civil.
pub(crate) fn format_date(unix_seconds: i64) -> String {
let (year, month, day) = civil(unix_seconds);
format!("{year:04}-{month:02}-{day:02}")
}
fn year_of(unix_ms: i64) -> i64 {
civil(unix_ms.div_euclid(1000)).0
}
fn civil(unix_seconds: i64) -> (i64, i64, i64) {
let days = unix_seconds.div_euclid(86_400);
let z = days + 719_468;
let era = z.div_euclid(146_097);
let doe = z.rem_euclid(146_097);
let yoe = (doe - doe / 1_460 + doe / 36_524 - doe / 146_096) / 365;
let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
let mp = (5 * doy + 2) / 153;
let day = doy - (153 * mp + 2) / 5 + 1;
let month = if mp < 10 { mp + 3 } else { mp - 9 };
let year = yoe + era * 400 + i64::from(month <= 2);
(year, month, day)
}
/// "5 min ago", "in 2 h", or a date for anything further away.
fn relative_time(at_ms: i64) -> String {
let now = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_millis() as i64)
.unwrap_or(0);
relative_to(at_ms, now)
}
pub(crate) fn relative_to(at_ms: i64, now_ms: i64) -> String {
let delta = (now_ms - at_ms) / 1000;
let (amount, future) = (delta.unsigned_abs(), delta < 0);
let text = match amount {
0..60 => {
return if future {
"soon".into()
} else {
"just now".into()
};
}
60..3_600 => format!("{} min", amount / 60),
3_600..86_400 => format!("{} h", amount / 3_600),
_ => return format_date(at_ms.div_euclid(1000)),
};
if future {
format!("in {text}")
} else {
format!("{text} ago")
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn formats_dates_durations_and_relative_times() {
assert_eq!(format_date(0), "1970-01-01");
assert_eq!(format_date(951_782_400), "2000-02-29");
assert_eq!(format_date(-86_400), "1969-12-31");
assert_eq!(format_duration_ms(59_600), "1:00");
assert_eq!(format_duration_ms(754_000), "12:34");
assert_eq!(format_duration_ms(3_723_000), "1:02:03");
let now = 1_700_000_000_000;
assert_eq!(relative_to(now - 30_000, now), "just now");
assert_eq!(relative_to(now - 5 * 60_000, now), "5 min ago");
assert_eq!(relative_to(now + 2 * 3_600_000, now), "in 2 h");
assert_eq!(relative_to(now - 3 * 86_400_000, now), "2023-11-11");
}
#[test]
fn fits_display_width_with_ellipsis() {
assert_eq!(fit_width("Выпуск 650", 20), "Выпуск 650");
assert_eq!(fit_width("Выпуск 650", 5), "Выпу…");
assert_eq!(fit_width("abc", 0), "");
}
}
+1564 -124
View File
File diff suppressed because it is too large. Load diff
+143
View File
@@ -0,0 +1,143 @@
use super::*;
use ratatui::{Terminal, backend::TestBackend};
fn playing_state() -> AppState {
let mut state = AppState::default();
state.player.current = Some(crate::library::models::TrackItem {
id: 1,
title: "Песня 界".into(),
track_number: None,
disc_number: None,
duration_seconds: 240.0,
artists: vec![],
featured_artists: vec![],
release_id: 1,
release_title: "Release".into(),
release_year: None,
cover_path: None,
file_path: "/unused/test.flac".into(),
content_id: None,
audio_format: None,
audio_bitrate: None,
audio_sample_rate: None,
audio_bit_depth: None,
file_size_bytes: None,
play_count: 0,
fed: None,
podcast: None,
});
state.player.playing = true;
state.player.position_secs = 12.0;
state
}
#[test]
fn footer_centers_version_and_aligns_visualization_under_volume() {
let mut state = playing_state();
for width in [160, 200] {
for shuffle in [false, true] {
state.player.shuffle = shuffle;
let mut terminal = Terminal::new(TestBackend::new(width, 2)).unwrap();
terminal
.draw(|frame| draw_status(frame, frame.area(), &state))
.unwrap();
let buffer = terminal.backend().buffer();
let version = format!("v{}", env!("CARGO_PKG_VERSION"));
// Count display cells, not UTF-8 bytes: the title is non-ASCII.
let volume_x = (0..width)
.find(|x| {
buffer[(*x, 0)].symbol() == "v"
&& *x + 2 < width
&& buffer[(*x + 1, 0)].symbol() == "o"
&& buffer[(*x + 2, 0)].symbol() == "l"
})
.unwrap();
let areas = footer_areas(Rect::new(0, 0, width, 2), &state);
assert_eq!(areas[2].x, volume_x);
assert_eq!(areas[2].y, 1);
assert_eq!(areas[2].right(), width);
let version_x = (width - version.len() as u16) / 2;
for (offset, ch) in version.chars().enumerate() {
assert_eq!(
buffer[(version_x + offset as u16, 1)].symbol(),
ch.to_string()
);
}
assert_eq!(
status_visualizer_area(Rect::new(0, 0, width, 24), &state).x,
volume_x
);
}
}
}
#[test]
fn footer_regions_do_not_overlap_on_narrow_terminals_or_command_input() {
let mut state = playing_state();
state.status_message = Some("long status message ".repeat(20));
for width in [1, 5, 8, 20, 40, 80, 120, 200] {
let areas = footer_areas(Rect::new(0, 0, width, 2), &state);
assert!(areas[0].right() <= areas[1].x);
assert!(areas[1].right() <= areas[2].x);
assert!(areas[2].right() <= width);
for command in [false, true] {
state.cmdline.active = command;
let mut terminal = Terminal::new(TestBackend::new(width, 2)).unwrap();
terminal
.draw(|frame| draw_status(frame, frame.area(), &state))
.unwrap();
// Neither messages nor the command prompt may paint the graph.
for x in areas[2].x..areas[2].right() {
assert_eq!(terminal.backend().buffer()[(x, 1)].symbol(), " ");
}
}
}
}
#[test]
fn status_animation_requires_local_unpaused_playback() {
let mut state = playing_state();
assert!(crate::visualizer::status::playing(&state));
state.player.paused = true;
assert!(!crate::visualizer::status::playing(&state));
assert!(crate::visualizer::status::visible(&state));
state.player.paused = false;
state.player.playing = false;
assert!(!crate::visualizer::status::playing(&state));
assert!(!crate::visualizer::status::visible(&state));
state.player.playing = true;
state.device_playback.role = crate::app::state::DevicePlaybackRole::Control;
assert!(!crate::visualizer::status::playing(&state));
}
#[test]
fn federation_mode_badge_stays_visible_at_the_right_edge() {
use crate::config::settings::LibrarySourceMode;
use ratatui::style::Color;
let mut state = playing_state();
for (mode, background) in [
(LibrarySourceMode::Local, Color::Yellow),
(LibrarySourceMode::My, Color::Cyan),
(LibrarySourceMode::Global, Color::Green),
] {
state.global.filters.source_mode = mode;
for width in [20, 40, 80, 160, 200] {
for playing in [false, true] {
state.player.playing = playing;
state.cmdline.active = !playing;
let mut terminal = Terminal::new(TestBackend::new(width, 2)).unwrap();
terminal
.draw(|frame| draw_status(frame, frame.area(), &state))
.unwrap();
let label = format!(" federation: {} ", mode.label());
let start = width - label.len() as u16;
for (offset, ch) in label.chars().enumerate() {
let cell = &terminal.backend().buffer()[(start + offset as u16, 0)];
assert_eq!(cell.symbol(), ch.to_string());
assert_eq!(cell.bg, background);
assert_eq!(cell.fg, Color::Black);
}
}
}
}
}
+72 -4
View File
@@ -1,20 +1,35 @@
use ratatui::style::{Color, Modifier, Style};
use crate::app::state::{AppState, DevicePlaybackRole};
pub const ACCENT: Color = Color::Cyan;
pub const CONTROL_ACCENT: Color = Color::Yellow;
pub const JAM_ACCENT: Color = Color::Magenta;
pub const DIM: Color = Color::DarkGray;
pub fn accent() -> Style {
Style::new().fg(ACCENT)
}
pub fn accent_for(state: &AppState) -> Style {
Style::new().fg(accent_color_for(state))
}
pub fn dim() -> Style {
Style::new().fg(DIM)
}
pub fn tab_active() -> Style {
pub fn tab_active_for(state: &AppState) -> Style {
Style::new()
.fg(Color::Black)
.bg(ACCENT)
.bg(accent_color_for(state))
.add_modifier(Modifier::BOLD)
}
pub fn danger_button() -> Style {
Style::new()
.fg(Color::White)
.bg(Color::Rgb(96, 0, 24))
.add_modifier(Modifier::BOLD)
}
@@ -22,6 +37,59 @@ pub fn selection() -> Style {
Style::new().fg(Color::White).bg(Color::Rgb(24, 68, 72))
}
pub fn header() -> Style {
Style::new().fg(ACCENT).add_modifier(Modifier::BOLD)
pub fn selection_for(state: &AppState) -> Style {
match state.device_playback.role {
DevicePlaybackRole::Jam => Style::new().fg(Color::White).bg(Color::Rgb(80, 24, 96)),
DevicePlaybackRole::Control => Style::new().fg(Color::White).bg(Color::Rgb(92, 72, 0)),
DevicePlaybackRole::Active => selection(),
}
}
pub fn header_for(state: &AppState) -> Style {
accent_for(state).add_modifier(Modifier::BOLD)
}
pub fn border_for(state: &AppState) -> Style {
match state.device_playback.role {
DevicePlaybackRole::Jam => Style::new().fg(JAM_ACCENT),
DevicePlaybackRole::Control => Style::new().fg(CONTROL_ACCENT),
DevicePlaybackRole::Active => dim(),
}
}
pub fn strong_border_for(state: &AppState) -> Style {
accent_for(state)
}
pub fn role_pill(role: DevicePlaybackRole) -> Style {
let bg = match role {
DevicePlaybackRole::Active => Color::Green,
DevicePlaybackRole::Control => CONTROL_ACCENT,
DevicePlaybackRole::Jam => JAM_ACCENT,
};
Style::new()
.fg(Color::Black)
.bg(bg)
.add_modifier(Modifier::BOLD)
}
pub fn source_mode_pill(mode: crate::config::settings::LibrarySourceMode) -> Style {
use crate::config::settings::LibrarySourceMode;
let bg = match mode {
LibrarySourceMode::Local => Color::Yellow,
LibrarySourceMode::My => Color::Cyan,
LibrarySourceMode::Global => Color::Green,
};
Style::new()
.fg(Color::Black)
.bg(bg)
.add_modifier(Modifier::BOLD)
}
fn accent_color_for(state: &AppState) -> Color {
match state.device_playback.role {
DevicePlaybackRole::Jam => JAM_ACCENT,
DevicePlaybackRole::Control => CONTROL_ACCENT,
DevicePlaybackRole::Active => ACCENT,
}
}
+432
View File
@@ -0,0 +1,432 @@
//! Manual portable-binary updates. All network/disk work runs off the UI thread.
use std::{
fs::File,
io::{Read, Write},
path::Path,
time::Duration,
};
use anyhow::{Context, Result, bail, ensure};
use object::Object;
use reqwest::blocking::Client;
use semver::Version;
use serde::Deserialize;
use sha2::{Digest, Sha256};
const REPOSITORY: &str = "https://api.github.com/repos/Furumi-stack/furumi-tui";
const MAX_ARCHIVE: u64 = 512 * 1024 * 1024;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Update {
pub version: String,
asset: Asset,
checksums: Asset,
}
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
struct Asset {
name: String,
browser_download_url: String,
}
#[derive(Deserialize)]
struct Release {
tag_name: String,
draft: bool,
prerelease: bool,
assets: Vec<Asset>,
}
#[derive(Debug, Default)]
pub struct State {
pub busy: bool,
pub installed: bool,
pub available: Option<Update>,
pub message: String,
}
fn client() -> Result<Client> {
// Reuse the ring backend already used by federation; respect an existing provider.
let _ = rustls::crypto::ring::default_provider().install_default();
Ok(Client::builder()
.user_agent(concat!("furumi/", env!("CARGO_PKG_VERSION")))
.https_only(true)
.connect_timeout(Duration::from_secs(10))
.timeout(Duration::from_secs(300))
.build()?)
}
fn read_limited(mut reader: impl Read, limit: u64) -> Result<Vec<u8>> {
let mut data = Vec::new();
reader.by_ref().take(limit + 1).read_to_end(&mut data)?;
ensure!(data.len() as u64 <= limit, "download exceeds size limit");
Ok(data)
}
fn select_release(release: Release, current: &str, os: &str, arch: &str) -> Result<Option<Update>> {
let version = release
.tag_name
.strip_prefix('v')
.unwrap_or(&release.tag_name);
let next = Version::parse(version).context("invalid release version")?;
if release.draft
|| release.prerelease
|| !next.pre.is_empty()
|| next <= Version::parse(current)?
{
return Ok(None);
}
let platform = match os {
"linux" => "linux",
"macos" => "macos",
"windows" => "windows",
_ => bail!("self-update is unsupported on {os}"),
};
let extension = if os == "windows" { "zip" } else { "tar.gz" };
let name = format!("furumi-{platform}-{arch}-{version}.{extension}");
let find = |name: &str| -> Result<Asset> {
let matches: Vec<_> = release
.assets
.iter()
.filter(|asset| asset.name == name)
.collect();
ensure!(matches.len() == 1, "release has no unique {name} asset");
Ok(matches[0].clone())
};
Ok(Some(Update {
version: version.to_owned(),
asset: find(&name)?,
checksums: find("SHA256SUMS")?,
}))
}
pub fn check() -> Result<Option<Update>> {
let response = client()?
.get(format!("{REPOSITORY}/releases/latest"))
.timeout(Duration::from_secs(20))
.send()?;
if response.status() == reqwest::StatusCode::NOT_FOUND {
return Ok(None);
}
let release = serde_json::from_slice(&read_limited(
response.error_for_status()?,
2 * 1024 * 1024,
)?)?;
select_release(
release,
env!("CARGO_PKG_VERSION"),
std::env::consts::OS,
std::env::consts::ARCH,
)
}
fn checksum(text: &str, name: &str) -> Result<String> {
let mut found = None;
for line in text.lines() {
let Some((hash, filename)) = line.split_once(' ') else {
continue;
};
if filename.trim_start().trim_start_matches('*') != name {
continue;
}
ensure!(found.is_none(), "duplicate checksum for {name}");
ensure!(
hash.len() == 64 && hash.bytes().all(|b| b.is_ascii_hexdigit()),
"invalid SHA-256 for {name}"
);
found = Some(hash.to_ascii_lowercase());
}
found.context("release does not contain a checksum for the selected archive")
}
fn extract(archive: &Path, name: &str, output: &mut File) -> Result<()> {
let binary = if cfg!(windows) {
"furumi.exe"
} else {
"furumi"
};
let root = name
.strip_suffix(".tar.gz")
.or_else(|| name.strip_suffix(".zip"))
.context("unsupported archive")?;
// Existing release archives omit the version in their inner directory.
let root = root.rsplit_once('-').context("invalid archive name")?.0;
let expected = format!("{root}/{binary}");
let mut count = 0;
if name.ends_with(".zip") {
let mut archive = zip::ZipArchive::new(File::open(archive)?)?;
for index in 0..archive.len() {
let mut entry = archive.by_index(index)?;
if entry.name() != expected {
continue;
}
ensure!(
entry.is_file() && !entry.is_symlink(),
"binary is not a regular file"
);
count += 1;
ensure!(count == 1, "duplicate binary in archive");
output.write_all(&read_limited(&mut entry, MAX_ARCHIVE)?)?;
}
} else {
let mut archive = tar::Archive::new(flate2::read::GzDecoder::new(File::open(archive)?));
for entry in archive.entries()? {
let mut entry = entry?;
if entry.path()?.as_ref() != Path::new(&expected) {
continue;
}
ensure!(
entry.header().entry_type().is_file(),
"binary is not a regular file"
);
count += 1;
ensure!(count == 1, "duplicate binary in archive");
output.write_all(&read_limited(&mut entry, MAX_ARCHIVE)?)?;
}
}
ensure!(count == 1, "archive does not contain {expected}");
output.sync_all()?;
Ok(())
}
fn validate_binary(current: &[u8], candidate: &[u8]) -> Result<()> {
let current = object::File::parse(current).context("cannot inspect installed binary")?;
let candidate = object::File::parse(candidate).context("invalid downloaded binary")?;
ensure!(
candidate.kind() == object::ObjectKind::Executable
|| candidate.kind() == object::ObjectKind::Dynamic,
"download is not an executable"
);
ensure!(
candidate.format() == current.format()
&& candidate.architecture() == current.architecture()
&& candidate.is_64() == current.is_64()
&& candidate.is_little_endian() == current.is_little_endian(),
"downloaded binary has incompatible platform or architecture"
);
Ok(())
}
pub fn install(update: &Update, mut progress: impl FnMut(String)) -> Result<()> {
let exe = std::env::current_exe()?.canonicalize()?;
let parent = exe.parent().context("executable has no parent directory")?;
let lock = File::options()
.read(true)
.write(true)
.create(true)
.truncate(false)
.open(parent.join(".furumi-update.lock"))
.context("cannot write to installation directory")?;
fs2::FileExt::try_lock_exclusive(&lock).context("another furumi instance is updating")?;
// Keep staging on the destination filesystem and never overwrite a running image.
let staging = tempfile::Builder::new()
.prefix(".furumi-update-")
.tempdir_in(parent)
.context("cannot create update staging directory")?;
let client = client()?;
let sums = read_limited(
client
.get(&update.checksums.browser_download_url)
.send()?
.error_for_status()?,
1024 * 1024,
)?;
let expected = checksum(std::str::from_utf8(&sums)?, &update.asset.name)?;
let mut response = client
.get(&update.asset.browser_download_url)
.send()?
.error_for_status()?;
let total = response.content_length();
ensure!(
total.is_none_or(|size| size <= MAX_ARCHIVE),
"archive exceeds size limit"
);
let archive = staging.path().join("download");
let mut file = File::create(&archive)?;
let mut hash = Sha256::new();
let mut buffer = [0u8; 64 * 1024];
let mut downloaded = 0u64;
let mut reported = u64::MAX;
loop {
let count = response.read(&mut buffer)?;
if count == 0 {
break;
}
downloaded += count as u64;
ensure!(downloaded <= MAX_ARCHIVE, "archive exceeds size limit");
file.write_all(&buffer[..count])?;
hash.update(&buffer[..count]);
let mb = downloaded / (1024 * 1024);
if mb != reported {
progress(format!("Downloading: {mb} MiB"));
reported = mb;
}
}
file.sync_all()?;
drop(file);
ensure!(
format!("{:x}", hash.finalize()) == expected,
"SHA-256 mismatch; update was not installed"
);
progress("Verifying binary...".into());
let binary = staging.path().join(if cfg!(windows) {
"furumi.exe"
} else {
"furumi"
});
let mut output = File::create(&binary)?;
extract(&archive, &update.asset.name, &mut output)?;
drop(output);
validate_binary(&std::fs::read(&exe)?, &std::fs::read(&binary)?)?;
std::fs::set_permissions(&binary, std::fs::metadata(&exe)?.permissions())?;
progress("Installing...".into());
self_replace::self_replace(&binary).context("could not replace executable")?;
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn https_client_can_be_constructed() {
client().unwrap();
}
#[test]
fn extracts_only_expected_binary_from_release_archives() {
let temp = tempfile::tempdir().unwrap();
let binary = if cfg!(windows) {
"furumi.exe"
} else {
"furumi"
};
let expected = format!("furumi-windows-x86_64/{binary}");
let payload = b"test executable";
let zip_path = temp.path().join("test.zip");
let mut zip = zip::ZipWriter::new(File::create(&zip_path).unwrap());
zip.start_file("README.md", zip::write::SimpleFileOptions::default())
.unwrap();
zip.write_all(b"readme").unwrap();
zip.start_file(&expected, zip::write::SimpleFileOptions::default())
.unwrap();
zip.write_all(payload).unwrap();
zip.finish().unwrap();
let output = temp.path().join("output");
extract(
&zip_path,
"furumi-windows-x86_64-0.1.6.zip",
&mut File::create(&output).unwrap(),
)
.unwrap();
assert_eq!(std::fs::read(&output).unwrap(), payload);
assert!(
extract(
&zip_path,
"furumi-linux-x86_64-0.1.6.zip",
&mut File::create(&output).unwrap()
)
.is_err()
);
let tar_path = temp.path().join("test.tar.gz");
let gzip = flate2::write::GzEncoder::new(
File::create(&tar_path).unwrap(),
flate2::Compression::default(),
);
let mut tar = tar::Builder::new(gzip);
let mut header = tar::Header::new_gnu();
header.set_size(payload.len() as u64);
header.set_mode(0o755);
header.set_cksum();
tar.append_data(&mut header, &expected, payload.as_slice())
.unwrap();
tar.into_inner().unwrap().finish().unwrap();
extract(
&tar_path,
"furumi-windows-x86_64-0.1.6.tar.gz",
&mut File::create(&output).unwrap(),
)
.unwrap();
assert_eq!(std::fs::read(&output).unwrap(), payload);
}
#[test]
fn binary_validation_rejects_wrong_architecture() {
let current = std::fs::read(std::env::current_exe().unwrap()).unwrap();
let mut other = current.clone();
// Change only the machine field, preserving an otherwise valid executable.
if current.starts_with(b"MZ") {
let pe = u32::from_le_bytes(current[0x3c..0x40].try_into().unwrap()) as usize;
let machine: u16 = if current[pe + 4..pe + 6] == [0x64, 0x86] {
0xaa64
} else {
0x8664
};
other[pe + 4..pe + 6].copy_from_slice(&machine.to_le_bytes());
} else if current.starts_with(b"\x7fELF") {
let machine: u16 = if current[18..20] == [62, 0] { 183 } else { 62 };
other[18..20].copy_from_slice(&machine.to_le_bytes());
} else if current.starts_with(&[0xcf, 0xfa, 0xed, 0xfe]) {
let cpu: u32 = if current[4] == 7 {
0x0100000c
} else {
0x01000007
};
other[4..8].copy_from_slice(&cpu.to_le_bytes());
} else {
panic!("unsupported test executable format");
}
assert!(validate_binary(&current, &other).is_err());
}
#[test]
fn checksums_require_exact_unique_valid_entry() {
let hash = "ab".repeat(32);
assert_eq!(
checksum(&format!("{hash} app.zip\n"), "app.zip").unwrap(),
hash
);
assert!(checksum(&format!("{hash} other.zip"), "app.zip").is_err());
assert!(checksum("broken app.zip", "app.zip").is_err());
assert!(checksum(&format!("{hash} app.zip\n{hash} app.zip"), "app.zip").is_err());
}
#[test]
fn release_selection_respects_semver_and_assets() {
let release = |version: &str| Release {
tag_name: version.into(),
draft: false,
prerelease: false,
assets: vec![
Asset {
name: "furumi-linux-x86_64-0.1.10.tar.gz".into(),
browser_download_url: String::new(),
},
Asset {
name: "SHA256SUMS".into(),
browser_download_url: String::new(),
},
],
};
assert!(
select_release(release("v0.1.10"), "0.1.9", "linux", "x86_64")
.unwrap()
.is_some()
);
assert!(
select_release(release("v0.1.8"), "0.1.9", "linux", "x86_64")
.unwrap()
.is_none()
);
assert!(
select_release(release("v0.2.0-beta.1"), "0.1.9", "linux", "x86_64")
.unwrap()
.is_none()
);
assert!(select_release(release("v0.1.10"), "0.1.9", "linux", "aarch64").is_err());
}
#[test]
fn binary_validation_rejects_corrupt_download() {
let current = std::fs::read(std::env::current_exe().unwrap()).unwrap();
validate_binary(&current, &current).unwrap();
assert!(validate_binary(&current, b"not a binary").is_err());
}
}
+279
View File
@@ -0,0 +1,279 @@
// name: Morphing cube
// protocol: furumi-visualizer-v2
// bundle-version: 6
//
// Audio-reactive neon wireframe, echo contours, core, shock rings, sparks
// and a bounded particle field. No native 3D API or retained state required.
// Echoes sample earlier rotation times with CURRENT audio; they are analytic
// trails, not stored frames. Particle lifetimes use time, rings also expand
// as the smoothed beat envelope decays. No beat history is available in v2.
//
// Fixed budgets: 8 mesh vertices, at most 48 particles + 24 short tails,
// 20 background stars, 3 rings, 2 echoes. Edges/rings use bulk trace commands.
// Smaller terminals omit echoes/rings and reduce particle counts.
fn clamp(v, lo, hi) {
if v < lo { lo } else if v > hi { hi } else { v }
}
fn min(a, b) { if a < b { a } else { b } }
fn rgb(r, g, b) {
to_int(clamp(r, 0.0, 255.0)) * 65536
+ to_int(clamp(g, 0.0, 255.0)) * 256
+ to_int(clamp(b, 0.0, 255.0))
}
// trace runs left-to-right. Swap endpoints for reversed edges and use
// vline for vertical ones (including an edge projected to a single cell).
fn edge(ax, ay, bx, by, fg, bg) {
if ax > bx {
let tx = ax; ax = bx; bx = tx;
let ty = ay; ay = by; by = ty;
}
if ax == bx {
return #{ op: "vline", x: ax, y: min(ay, by),
h: abs(to_float(by - ay)).to_int() + 1, ch: "|", fg: fg, bg: bg };
}
let dx = bx - ax;
let dy = by - ay;
let ch = if abs(to_float(dy)) * 3.0 < to_float(dx) { "-" }
else if abs(to_float(dy)) > to_float(dx) { "|" }
else if dy < 0 { "/" } else { "\\" };
let ys = [];
let slope = to_float(dy) / to_float(dx);
for x in 0..=dx {
ys.push(to_int(to_float(ay) + to_float(x) * slope + 0.5));
}
#{ op: "trace", x: ax, ys: ys, ch: ch, line_ch: ch,
fg: fg, line_fg: fg, bg: bg }
}
// Lift quieter passages without a hard gain/clipping threshold.
fn response(level) { 1.0 - pow(1.0 - clamp(level, 0.0, 1.0), 1.6) }
fn palette(t, heat, light) {
rgb((95.0 + 125.0 * heat + 35.0 * sin(t * 0.43)) * light,
(185.0 - 95.0 * heat + 55.0 * sin(t * 0.31 + 1.3)) * light,
255.0 * light)
}
// A single projected mesh, fitted uniformly: never clamp individual corners.
fn mesh(t, energy, bass, mid, treble, beat, width, height) {
let pulse = 0.70 + energy * 0.45 + beat * 0.85;
let sx = pulse * (1.0 + bass * 0.55);
let sy = pulse * (1.0 - bass * 0.42 + mid * 0.15);
let sz = pulse * (1.0 + treble * 0.22);
// A bounded beat kick, not time * instantaneous_energy (which jumps).
let ax = t * 0.47 + 0.35 + beat * 0.22 * sin(t * 1.3);
let ay = t * 0.63 + 0.55;
let az = t * 0.23 + beat * 0.16 * cos(t * 0.7);
let cx = cos(ax); let snx = sin(ax);
let cy = cos(ay); let sny = sin(ay);
let cz = cos(az); let snz = sin(az);
let twist = mid * 0.95 * sin(t * 0.83);
let ct = cos(twist); let st = sin(twist);
let vertices = [
[-1.0, -1.0, -1.0], [1.0, -1.0, -1.0],
[1.0, 1.0, -1.0], [-1.0, 1.0, -1.0],
[-1.0, -1.0, 1.0], [1.0, -1.0, 1.0],
[1.0, 1.0, 1.0], [-1.0, 1.0, 1.0]
];
let projected = [];
let extent = 0.01;
for i in 0..8 {
let v = vertices[i];
let pull = 1.0 + treble * 0.38 * sin(t * 2.3 + to_float(i) * 2.4)
+ beat * 0.14 * cos(to_float(i) * 1.7 + t);
let x = v[0] * sx * pull;
let y = v[1] * sy * pull;
let z = v[2] * sz * pull;
let xt = x * ct + z * st * v[1];
let zt = z * ct - x * st * v[1];
let y1 = y * cx - zt * snx;
let z1 = y * snx + zt * cx;
let x2 = xt * cy + z1 * sny;
let z2 = z1 * cy - xt * sny;
let x3 = x2 * cz - y1 * snz;
let y3 = x2 * snz + y1 * cz;
// Even the largest deformed vertex stays < 6.4 from the origin.
let perspective = 10.0 / (10.0 + z2);
let px = x3 * perspective;
let py = y3 * perspective;
if abs(px) > extent { extent = abs(px); }
if abs(py) > extent { extent = abs(py); }
projected.push([px, py, z2]);
}
// CELL_ASPECT is cell height / width; adjust for a different font.
let CELL_ASPECT = 2.0;
let span = min(to_float(width - 4) / CELL_ASPECT, to_float(height - 4));
let scale = span * min(0.23, 0.46 / extent);
let center_x = to_float(width - 1) * 0.5;
let center_y = to_float(height - 1) * 0.5;
let points = [];
for p in projected {
points.push([to_int(center_x + p[0] * scale * CELL_ASPECT + 0.5),
to_int(center_y + p[1] * scale + 0.5), p[2]]);
}
points
}
// Method calls mutate the command array in place; don't copy it into helpers.
fn dot(x, y, ch, fg, bg, width, height) {
let px = to_int(x + 0.5); let py = to_int(y + 0.5);
if x >= 0.0 && y >= 1.0 && px < width && py < height - 1 {
this.push(#{ op: "cell", x: px, y: py, ch: ch, fg: fg, bg: bg });
}
}
fn render(input) {
let bg = 0x020610;
let cmds = [#{ op: "clear", bg: bg }];
if input.width < 12 || input.height < 8 { return cmds; }
let w = input.width; let h = input.height;
let t = input.time;
let energy = response(input.energy);
let bass = response(input.bass);
let mid = response(input.mid);
let treble = response(input.treble);
let beat = response(input.beat);
let drive = clamp(energy * 0.4 + treble * 0.3 + beat * 0.8, 0.0, 1.0);
let small = w < 40 || h < 16;
let center_x = to_float(w - 1) * 0.5;
let center_y = to_float(h - 1) * 0.5;
let span = min(to_float(w - 4) * 0.5, to_float(h - 4));
let points = mesh(t, energy, bass, mid, treble, beat, w, h);
let edges = [[0,1], [1,2], [2,3], [3,0], [4,5], [5,6],
[6,7], [7,4], [0,4], [1,5], [2,6], [3,7]];
// Sparse drifting starfield; deterministic, independent of audio hardware.
let stars = if small { 8 } else { 20 };
for i in 0..stars {
let phase = to_float(i);
let x = (phase * 37.71 + t * (0.3 + to_float(i % 3) * 0.2)) % to_float(w - 1);
let y = 1.0 + (phase * 13.37) % to_float(h - 3);
let light = 0.12 + treble * 0.16 * (0.5 + 0.5 * sin(t * 2.0 + phase));
cmds.dot(x, y, ".", palette(t, 0.0, light), bg, w, h);
}
// Three elliptical shock fronts. On a transient they brighten and
// spread; release of the beat envelope carries them farther outward.
if !small && drive > 0.04 {
for ring in 0..3 {
let phase = (t * 0.45 + to_float(ring) / 3.0) % 1.0;
let radius = 0.22 + phase * 0.55 + (1.0 - beat) * 0.18;
let rx = span * radius;
let ry = span * radius * (0.22 + mid * 0.10);
let left = to_int(center_x - rx);
let right = to_int(center_x + rx);
let top = []; let bottom = [];
for x in left..=right {
let nx = clamp((to_float(x) - center_x) / rx, -1.0, 1.0);
let dy = sqrt(1.0 - nx * nx) * ry;
top.push(to_int(center_y - dy + 0.5));
bottom.push(to_int(center_y + dy + 0.5));
}
let fg = palette(t + to_float(ring), beat, (1.0 - phase) * (0.12 + beat * 0.45 + bass * 0.12));
for ys in [top, bottom] {
cmds.push(#{ op: "trace", x: left, ys: ys, ch: ".", line_ch: ".",
fg: fg, line_fg: fg, bg: bg });
}
}
}
// Particles launch from the eight corners with staggered lifetimes.
// Speed/age depend on time; audio changes reach and brightness instead
// of rescaling time and teleporting particles on each audio update.
if drive > 0.04 {
let particles = if small { 16 } else { 48 };
for i in 0..particles {
let fi = to_float(i);
let age = (t * (0.27 + to_float(i % 5) * 0.025) + fi * 0.618034) % 1.0;
let angle = fi * 2.39996 + t * 0.16;
let dx = cos(angle); let dy = sin(angle);
let origin = points[i % 8];
let travel = span * (0.35 + energy * 0.55 + beat * 0.8);
let distance = age * travel;
let light = sin(age * 3.14159) * (0.15 + drive * 0.85);
let fg = palette(t + fi * 0.13, beat, light);
let ch = if beat > 0.45 && i % 3 == 0 { "*" } else if treble > 0.35 { "+" } else { "." };
if !small && i % 2 == 0 {
let tail = distance - span * 0.04;
cmds.dot(to_float(origin[0]) + dx * tail * 2.0,
to_float(origin[1]) + dy * tail, ".", palette(t, beat, light * 0.3), bg, w, h);
}
cmds.dot(to_float(origin[0]) + dx * distance * 2.0,
to_float(origin[1]) + dy * distance, ch, fg, bg, w, h);
}
}
// Analytic motion echoes. These are recomputed poses, not frame history.
if !small && drive > 0.04 {
for echo in [2, 1] {
let lag = to_float(echo) * (0.14 + beat * 0.10);
let ghost = mesh(t - lag, energy, bass, mid, treble, beat, w, h);
let fg = palette(t + to_float(echo), 1.0 - beat, (0.08 + drive * 0.16) / to_float(echo));
for e in edges {
let a = ghost[e[0]]; let b = ghost[e[1]];
cmds.push(edge(a[0], a[1], b[0], b[1], fg, bg));
}
}
}
// A warm inner cage gives depth and a second pulse inside the main mesh.
if !small {
let inner = [];
let size = 0.35 + beat * 0.25;
for p in points {
inner.push([to_int(center_x + (to_float(p[0]) - center_x) * size + 0.5),
to_int(center_y + (to_float(p[1]) - center_y) * size + 0.5)]);
}
let fg = rgb(100.0 + beat * 155.0, 45.0 + energy * 75.0, 65.0 + treble * 70.0);
for e in edges {
let a = inner[e[0]]; let b = inner[e[1]];
cmds.push(edge(a[0], a[1], b[0], b[1], fg, bg));
}
}
let ordered = [];
for e in edges {
let depth = (points[e[0]][2] + points[e[1]][2]) * 0.5;
let at = 0;
while at < ordered.len() && ordered[at][2] > depth { at += 1; }
ordered.insert(at, [e[0], e[1], depth]);
}
for e in ordered {
let a = points[e[0]]; let b = points[e[1]];
let light = clamp(0.78 - e[2] * 0.14 + beat * 0.12, 0.3, 1.0);
cmds.push(edge(a[0], a[1], b[0], b[1], palette(t, beat, light), bg));
}
// Sparks travel along edges; no more than twelve extra cells.
if treble > 0.08 || beat > 0.08 {
for i in 0..12 {
let e = edges[i]; let a = points[e[0]]; let b = points[e[1]];
let phase = (t * 0.8 + to_float(i) * 0.137) % 1.0;
cmds.dot(to_float(a[0]) + to_float(b[0] - a[0]) * phase,
to_float(a[1]) + to_float(b[1] - a[1]) * phase,
"*", 0xffe8c0, bg, w, h);
}
}
for p in points {
if !small && beat > 0.45 {
let glow = palette(t, beat, beat * 0.45);
for offset in [[-1,0], [1,0], [0,-1], [0,1]] {
cmds.dot(to_float(p[0] + offset[0]), to_float(p[1] + offset[1]), "+", glow, bg, w, h);
}
}
cmds.push(#{ op: "cell", x: p[0], y: p[1], ch: "o", fg: 0xe8f6ff, bg: bg });
}
if input.show_clock {
cmds.push(#{ op: "text", x: 1, y: 0, text: input.clock, fg: 0xa6cde0, bg: bg });
}
if input.paused {
cmds.push(#{ op: "text", x: w - 7, y: 0, text: "paused", fg: 0xa6cde0, bg: bg });
}
if w >= 16 {
cmds.push(#{ op: "text", x: 1, y: h - 1, text: "MORPHING CUBE", fg: 0x527b98, bg: bg });
}
cmds
}
+393
View File
@@ -0,0 +1,393 @@
// name: Pulsing sphere
// protocol: furumi-visualizer-v2
// bundle-version: 5
//
// A second bundled example with a very different structure from
// scope_spectrum.rhai: instead of a waveform-first visual, it renders a
// hollow terminal "sphere" whose radius, halo and palette respond to audio.
//
// Script entry point:
// fn render(input) -> Array<Map>
//
// Input map fields supplied by Furumi:
// width, height terminal size in cells
// time, position, progress animation time and playback progress
// volume, paused player state
// energy, bass, mid, treble smoothed audio bands in the 0.0..1.0 range
// beat transient pulse estimate in the 0.0..1.0 range
// seed stable per-track number in the 0.0..1.0 range
// samples recent mono waveform samples in the -1.0..1.0 range
// show_clock, clock user setting and formatted clock text
// track_title, track_artist metadata strings
//
// Useful numeric helpers available to scripts:
// to_int, to_float Rhai conversions
// sin, cos, tan, sqrt, abs, pow
// Scripts cannot import modules; keep every visualization self-contained.
//
// Draw command maps returned from render(input):
// #{ op: "clear", bg: 0x000000 }
// #{ op: "cell", x: 10, y: 4, ch: "*", fg: 0x33ffee, bg: 0x000000 }
// #{ op: "hline", x: 0, y: 4, w: 20, ch: "-", fg: 0x33ffee, bg: 0x000000 }
// #{ op: "vline", x: 10, y: 0, h: 12, ch: "|", fg: 0x33ffee, bg: 0x000000 }
// #{ op: "rect", x: 10, y: 6, w: 2, h: 4, ch: "#", fg: 0x33ffee, bg: 0x000000 }
// #{ op: "trace", x: 0, ys: [4, 5, 3], ch: "*", line_ch: "|", fg: 0xffffff, line_fg: 0x558888, bg: 0x000000 }
// #{ op: "text", x: 2, y: 1, text: "hello", fg: 0xffffff, bg: 0x000000 }
//
// This script intentionally uses every command type. The sphere itself stays
// hollow: trace commands draw its spectral outline and orbit, hline draws
// latitudes, rect/vline draw the small energy meter, cells create stars and
// burst nodes, and labels use text.
fn clamp(value, low, high) {
if value < low {
low
} else if value > high {
high
} else {
value
}
}
fn min(left, right) {
if left < right { left } else { right }
}
fn max(left, right) {
if left > right { left } else { right }
}
fn rgb(r, g, b) {
let rr = to_int(clamp(r, 0, 255));
let gg = to_int(clamp(g, 0, 255));
let bb = to_int(clamp(b, 0, 255));
rr * 65536 + gg * 256 + bb
}
fn lerp(left, right, mix) {
left * (1.0 - mix) + right * mix
}
fn sample_at(samples, nx) {
let len = samples.len();
if len <= 0 {
0.0
} else {
let pos = clamp(nx, 0.0, 1.0) * (len - 1);
let left = to_int(pos);
let right = if left + 1 < len { left + 1 } else { left };
let mix = pos - to_float(left);
lerp(samples[left], samples[right], mix)
}
}
fn cell(x, y, ch, fg, bg) {
#{ op: "cell", x: x, y: y, ch: ch, fg: fg, bg: bg }
}
fn hline(x, y, w, ch, fg, bg) {
#{ op: "hline", x: x, y: y, w: w, ch: ch, fg: fg, bg: bg }
}
fn vline(x, y, h, ch, fg, bg) {
#{ op: "vline", x: x, y: y, h: h, ch: ch, fg: fg, bg: bg }
}
fn rect(x, y, w, h, ch, fg, bg) {
#{ op: "rect", x: x, y: y, w: w, h: h, ch: ch, fg: fg, bg: bg }
}
fn trace(x, ys, ch, line_ch, fg, line_fg, bg) {
#{ op: "trace", x: x, ys: ys, ch: ch, line_ch: line_ch, fg: fg, line_fg: line_fg, bg: bg }
}
fn text(x, y, value, fg, bg) {
#{ op: "text", x: x, y: y, text: value, fg: fg, bg: bg }
}
// A time-varying RGB palette. "shade" is usually 0.0..1.0; larger values are
// allowed and clamped by rgb(). Audio bands shift the hue without Rust knowing
// anything about the visual.
fn palette(input, shade, phase) {
let t = input.time + input.seed * 8.0 + phase;
let bass_push = input.bass * 70.0;
let treble_push = input.treble * 65.0;
rgb(
50 + shade * 130 + sin(t * 0.90) * 55 + bass_push,
70 + shade * 115 + sin(t * 0.63 + 2.1) * 55 + input.mid * 55,
95 + shade * 145 + cos(t * 0.72 + 0.7) * 55 + treble_push
)
}
fn wrap01(value) {
let out = value;
while out < 0.0 {
out += 1.0;
}
while out > 1.0 {
out -= 1.0;
}
out
}
fn spectral_band(input, phase) {
if phase < 0.34 {
input.bass
} else if phase < 0.68 {
input.mid
} else {
input.treble
}
}
// Treat the waveform as if it was wrapped around the sphere. The returned
// value is a radial spike amount: low frequencies push broad parts of the
// contour, raw samples add sharp teeth, and beat makes the edge jump outward.
fn edge_spectrum(input, phase) {
let p = wrap01(phase);
let wave = abs(sample_at(input.samples, p));
let neighbor = abs(sample_at(input.samples, wrap01(p + 0.021)));
let band = spectral_band(input, p);
let flutter = abs(sin(input.time * (5.0 + p * 7.0) + p * 38.0 + input.seed * 9.0));
let fine = abs(cos(input.time * (8.0 + p * 4.0) - p * 71.0));
clamp(
wave * (0.62 + input.energy * 0.36)
+ neighbor * 0.24
+ band * 0.46
+ input.beat * (0.30 + flutter * 0.64)
+ fine * input.energy * 0.18,
0.0,
1.55
)
}
fn push_starfield(cmds, input, bg) {
let stars = 34;
let index = 0;
while index < stars {
let x = (index * 37 + to_int(input.seed * 1000.0)) % max(input.width, 1);
let y = (index * 17 + to_int(input.time * 2.0)) % max(input.height, 1);
let speed = 0.7 + to_float(index % 5) * 0.15;
let twinkle = abs(sin(input.time * speed + to_float(index)));
let fg = rgb(
45 + twinkle * 120 + input.treble * 80,
75 + twinkle * 120,
105 + twinkle * 130
);
let ch = if twinkle + input.beat > 1.25 { "*" } else { "." };
cmds.push(cell(x, y, ch, fg, bg));
index += 1;
}
cmds
}
fn push_orbit(cmds, input, cx, cy, rx, ry, bg) {
let width = max(rx * 2 + 9, 3);
let start_x = max(cx - width / 2, 0);
let max_w = input.width - start_x;
let actual_w = min(width, max_w);
let back = [];
let front = [];
let i = 0;
while i < actual_w {
let nx = to_float(i) / to_float(max(actual_w - 1, 1));
let angle = nx * 6.28318 + input.time * 0.85;
let sample = sample_at(input.samples, nx);
let wobble = (sin(angle + input.bass * 2.0) + sample * 0.28)
* to_float(max(ry, 1))
* (0.28 + input.energy * 0.10);
let y_front = to_int(clamp(
to_float(cy) + wobble + input.beat * 1.5,
0.0,
to_float(input.height - 1)
));
let y_back = to_int(clamp(
to_float(cy) - wobble - input.beat * 1.5,
0.0,
to_float(input.height - 1)
));
front.push(y_front);
back.push(y_back);
i += 1;
}
let back_fg = palette(input, 0.18, 3.4);
let front_fg = palette(input, 0.65 + input.beat * 0.25, 0.5);
cmds.push(trace(start_x, back, ".", ".", back_fg, back_fg, bg));
cmds.push(trace(start_x, front, "*", ".", front_fg, front_fg, bg));
cmds
}
fn push_pulse_ring(cmds, input, cx, cy, rx, ry, bg) {
let ring_rx = rx + 2 + to_int(input.beat * 5.0 + input.energy * 2.0);
let ring_ry = ry + 1 + to_int(input.beat * 3.0 + input.bass * 2.0);
let left = max(cx - ring_rx, 0);
let right = min(cx + ring_rx, input.width - 1);
let width = right - left + 1;
if width <= 2 {
return cmds;
}
let top = [];
let bottom = [];
let i = 0;
while i < width {
let nx = if width > 1 { to_float(i) / to_float(width - 1) * 2.0 - 1.0 } else { 0.0 };
let phase = to_float(i) / to_float(max(width - 1, 1));
let inside = max(1.0 - nx * nx, 0.0);
let spike = edge_spectrum(input, phase) * (1.0 + input.energy * 3.0 + input.beat * 2.0);
let y = sqrt(inside) * (to_float(ring_ry) + spike);
top.push(to_int(clamp(to_float(cy) - y, 0.0, to_float(input.height - 1))));
bottom.push(to_int(clamp(to_float(cy) + y, 0.0, to_float(input.height - 1))));
i += 1;
}
let color = palette(input, 0.14 + input.beat * 0.35, 4.8);
cmds.push(trace(left, top, ".", ".", color, color, bg));
cmds.push(trace(left, bottom, ".", ".", color, color, bg));
cmds
}
fn push_sphere(cmds, input, cx, cy, rx, ry, bg) {
let left = max(cx - rx, 0);
let right = min(cx + rx, input.width - 1);
let width = right - left + 1;
if width <= 2 {
return cmds;
}
let top = [];
let bottom = [];
let glow_top = [];
let glow_bottom = [];
let i = 0;
while i < width {
let nx = if width > 1 { to_float(i) / to_float(width - 1) * 2.0 - 1.0 } else { 0.0 };
let inside = max(1.0 - nx * nx, 0.0);
let phase = to_float(i) / to_float(max(width - 1, 1));
let top_spike = edge_spectrum(input, phase) * (1.0 + input.energy * 3.4 + input.beat * 3.0);
let bottom_spike = edge_spectrum(input, 1.0 - phase) * (1.0 + input.energy * 3.4 + input.beat * 3.0);
let edge = sqrt(inside) * to_float(ry);
let top_y = to_int(clamp(to_float(cy) - edge - top_spike, 0.0, to_float(input.height - 1)));
let bottom_y = to_int(clamp(to_float(cy) + edge + bottom_spike, 0.0, to_float(input.height - 1)));
let glow = 1 + to_int(max(top_spike, bottom_spike) * 0.35 + input.beat * 2.0);
top.push(top_y);
bottom.push(bottom_y);
glow_top.push(clamp(top_y - glow, 0, input.height - 1));
glow_bottom.push(clamp(bottom_y + glow, 0, input.height - 1));
i += 1;
}
let glow = palette(input, 0.22 + input.energy * 0.22, 3.1);
let outline = palette(input, 0.82 + input.beat * 0.45, 0.3);
let bridge = palette(input, 0.42 + input.mid * 0.25, 2.2);
cmds.push(trace(left, glow_top, ".", ".", glow, glow, bg));
cmds.push(trace(left, glow_bottom, ".", ".", glow, glow, bg));
cmds.push(trace(left, top, "*", ".", outline, bridge, bg));
cmds.push(trace(left, bottom, "*", ".", outline, bridge, bg));
let equator = palette(input, 0.50 + input.bass * 0.25, 5.6);
cmds.push(hline(left, cy, width, "-", equator, bg));
if ry > 4 {
let latitude = palette(input, 0.35 + input.treble * 0.20, 1.8);
let span = max(width - width / 3, 3);
let lat_x = left + (width - span) / 2;
let lat_y = max(cy - ry / 2, 0);
cmds.push(hline(lat_x, lat_y, span, ".", latitude, bg));
cmds.push(hline(lat_x, min(cy + ry / 2, input.height - 1), span, ".", latitude, bg));
}
let nodes = 42;
let node = 0;
while node < nodes {
let phase = to_float(node) / to_float(nodes);
let angle = phase * 6.28318 + input.time * (0.10 + input.treble * 0.08);
let spectrum = edge_spectrum(input, phase);
let burst = spectrum * (1.4 + input.energy * 4.2 + input.beat * 3.5);
let x = to_int(clamp(to_float(cx) + cos(angle) * (to_float(rx) + burst), 0.0, to_float(input.width - 1)));
let y = to_int(clamp(to_float(cy) + sin(angle) * (to_float(ry) + burst * 0.58), 0.0, to_float(input.height - 1)));
let fg = palette(input, 0.48 + spectrum * 0.36 + input.beat * 0.30, angle);
let ch = if spectrum > 1.05 { "*" } else if spectrum > 0.72 { "+" } else { "." };
cmds.push(cell(x, y, ch, fg, bg));
if spectrum > 1.18 {
let spike_x = to_int(clamp(to_float(cx) + cos(angle) * (to_float(rx) + burst + 1.5), 0.0, to_float(input.width - 1)));
let spike_y = to_int(clamp(to_float(cy) + sin(angle) * (to_float(ry) + (burst + 1.5) * 0.58), 0.0, to_float(input.height - 1)));
cmds.push(cell(spike_x, spike_y, ".", fg, bg));
}
node += 1;
}
cmds
}
fn push_meter(cmds, input, bg) {
if input.height < 5 || input.width < 20 {
return cmds;
}
let y = input.height - 2;
let w = min(input.width - 4, 48);
let x = 2;
let base = rgb(18, 34, 42);
let fill = palette(input, 0.65 + input.energy * 0.35, 5.2);
let filled = to_int(clamp(input.energy * to_float(w), 1.0, to_float(w)));
cmds.push(hline(x, y, w, "-", base, bg));
cmds.push(rect(x, y, filled, 1, " ", fill, fill));
let progress = to_int(clamp(input.progress * to_float(w), 0.0, to_float(w)));
if progress > 0 {
cmds.push(hline(x, y - 1, progress, ".", fill, bg));
cmds.push(vline(min(x + progress, x + w - 1), y - 1, 2, "|", fill, bg));
}
cmds
}
fn push_labels(cmds, input, bg) {
let fg = rgb(180 + input.treble * 60, 230, 245);
let dim = rgb(70, 120 + input.energy * 80, 130 + input.energy * 80);
if input.show_clock {
cmds.push(text(1, 0, " " + input.clock + " ", fg, rgb(2, 18, 24)));
}
if input.track_title != "" && input.height > 4 {
cmds.push(text(2, input.height - 1, input.track_title, fg, bg));
}
if input.track_artist != "" && input.height > 5 {
cmds.push(text(2, input.height - 3, input.track_artist, dim, bg));
}
if input.paused {
cmds.push(text(2, 1, "paused", dim, bg));
}
cmds
}
fn render(input) {
let cmds = [];
let bg = rgb(1, 4, 10);
cmds.push(#{ op: "clear", bg: bg });
if input.width <= 8 || input.height <= 6 {
return cmds;
}
cmds = push_starfield(cmds, input, bg);
let cx = input.width / 2;
let cy = input.height / 2;
let max_ry = max((input.height - 6) / 2, 2);
let max_rx = max(input.width / 3, 4);
let base = min(to_float(max_ry), to_float(max_rx) / 2.0) * 0.78;
let activity = clamp(input.energy * 0.72 + input.bass * 0.50 + input.beat * 1.00, 0.0, 1.18);
let pulse = 0.34
+ activity * 0.58
+ input.volume * 0.04
+ input.beat * 0.18
+ abs(sin(input.time * 2.8 + input.position * 0.07)) * (0.03 + input.energy * 0.07);
let ry = max(to_int(base * pulse), 2);
let rx = max(to_int(to_float(ry) * (1.85 + input.treble * 0.28)), 4);
cmds = push_pulse_ring(cmds, input, cx, cy, rx, ry, bg);
cmds = push_orbit(cmds, input, cx, cy, rx, ry, bg);
cmds = push_sphere(cmds, input, cx, cy, rx, ry, bg);
cmds = push_meter(cmds, input, bg);
cmds = push_labels(cmds, input, bg);
cmds
}
+274
View File
@@ -0,0 +1,274 @@
// name: Scope spectrum
// protocol: furumi-visualizer-v2
// bundle-version: 5
//
// This bundled script is both a preset and an API example. It demonstrates
// every drawing command currently understood by Furumi's visualizer runtime:
// clear, cell, hline, vline, rect, trace and text.
//
// Script entry point:
// fn render(input) -> Array<Map>
//
// Important input fields:
// width, height terminal size in cells
// time, position, progress animation time and playback progress
// volume, paused player state
// energy, bass, mid, treble smoothed audio bands in the 0.0..1.0 range
// beat transient pulse estimate in the 0.0..1.0 range
// samples recent mono waveform samples in the -1.0..1.0 range
// show_clock, clock user setting and formatted clock text
// track_title, track_artist metadata for optional labels
//
// Useful numeric helpers available to scripts:
// to_int, to_float Rhai conversions
// sin, cos, tan, sqrt, abs, pow
// Scripts cannot import modules; keep every visualization self-contained.
//
// Return value: an array of command maps. Colors are 0xRRGGBB integers.
// #{ op: "clear", bg: 0x000000 }
// #{ op: "cell", x: 10, y: 4, ch: "*", fg: 0x33ffee, bg: 0x000000 }
// #{ op: "hline", x: 0, y: 4, w: 20, ch: "-", fg: 0x33ffee, bg: 0x000000 }
// #{ op: "vline", x: 10, y: 0, h: 12, ch: "|", fg: 0x33ffee, bg: 0x000000 }
// #{ op: "rect", x: 10, y: 6, w: 2, h: 4, ch: "#", fg: 0x33ffee, bg: 0x000000 }
// #{ op: "trace", x: 0, ys: [4, 5, 3], ch: "*", line_ch: "|", fg: 0xffffff, line_fg: 0x558888, bg: 0x000000 }
// #{ op: "text", x: 2, y: 1, text: "hello", fg: 0xffffff, bg: 0x000000 }
//
// Performance tip: prefer hline/vline/rect/trace for large shapes and reserve
// cell for isolated details. Crossing the Rhai -> Rust boundary once per cell
// is much slower than returning one bulk command.
fn clamp(value, low, high) {
if value < low {
low
} else if value > high {
high
} else {
value
}
}
fn min(left, right) {
if left < right { left } else { right }
}
fn rgb(r, g, b) {
let rr = to_int(clamp(r, 0, 255));
let gg = to_int(clamp(g, 0, 255));
let bb = to_int(clamp(b, 0, 255));
rr * 65536 + gg * 256 + bb
}
fn lerp(left, right, mix) {
left * (1.0 - mix) + right * mix
}
fn sample_at(samples, nx) {
let len = samples.len();
if len <= 0 {
0.0
} else {
let pos = clamp(nx, 0.0, 1.0) * (len - 1);
let left = to_int(pos);
let right = if left + 1 < len { left + 1 } else { left };
let mix = pos - to_float(left);
lerp(samples[left], samples[right], mix)
}
}
fn cell(x, y, ch, fg, bg) {
#{ op: "cell", x: x, y: y, ch: ch, fg: fg, bg: bg }
}
fn hline(x, y, w, ch, fg, bg) {
#{ op: "hline", x: x, y: y, w: w, ch: ch, fg: fg, bg: bg }
}
fn vline(x, y, h, ch, fg, bg) {
#{ op: "vline", x: x, y: y, h: h, ch: ch, fg: fg, bg: bg }
}
fn rect(x, y, w, h, ch, fg, bg) {
#{ op: "rect", x: x, y: y, w: w, h: h, ch: ch, fg: fg, bg: bg }
}
fn trace(x, ys, ch, line_ch, fg, line_fg, bg) {
#{ op: "trace", x: x, ys: ys, ch: ch, line_ch: line_ch, fg: fg, line_fg: line_fg, bg: bg }
}
fn text(x, y, value, fg, bg) {
#{ op: "text", x: x, y: y, text: value, fg: fg, bg: bg }
}
fn draw_grid(width, height, progress, energy, bg) {
let cmds = [];
let grid = rgb(22, 48 + energy * 30, 54 + energy * 35);
let center = height / 2;
let x = 0;
while x < width {
cmds.push(vline(x, 0, height, ".", grid, bg));
x += 12;
}
let y = 0;
while y < height {
cmds.push(hline(0, y, width, ".", grid, bg));
y += 4;
}
cmds.push(hline(0, center, width, "-", grid, bg));
let cross_x = 0;
while cross_x < width {
let cross_y = 0;
while cross_y < height {
cmds.push(cell(cross_x, cross_y, "+", grid, bg));
cross_y += 4;
}
cmds.push(cell(cross_x, center, "+", grid, bg));
cross_x += 12;
}
let scan_x = to_int(progress * to_float(width - 1));
let scan = rgb(25, 120 + energy * 80, 130 + energy * 80);
cmds.push(vline(scan_x, 0, height, "|", scan, bg));
cmds
}
fn draw_scope(input, scope_height, bg) {
let cmds = [];
let width = input.width;
if width <= 0 || scope_height <= 0 {
return cmds;
}
let center = to_float(scope_height - 1) / 2.0;
let half = center;
let fg = rgb(55 + input.beat * 80, 230, 210 + input.treble * 45);
let bridge = rgb(20, 120 + input.energy * 70, 115 + input.energy * 60);
let amplitude = 0.74 + input.energy * 0.55 + input.beat * 0.10;
let ys = [];
let x = 0;
while x < width {
let nx = if width > 1 { to_float(x) / to_float(width - 1) } else { 0.0 };
let sample = sample_at(input.samples, nx) * amplitude;
let y = to_int(clamp(center - sample * half, 0.0, to_float(scope_height - 1)));
ys.push(y);
x += 1;
}
cmds.push(trace(0, ys, "*", "|", fg, bridge, bg));
cmds
}
fn spectrum_value(freq, input) {
let band = if freq < 0.28 {
input.bass
} else if freq < 0.68 {
input.mid
} else {
input.treble
};
let wobble = abs(sin(input.time * (1.7 + freq * 5.0) + input.seed * 17.0 + freq * 31.0));
let harmonic = abs(cos(input.time * 0.63 - freq * 23.0));
clamp(0.06 + band * (0.30 + wobble * 0.48 + harmonic * 0.18) + input.beat * (1.0 - freq) * 0.35, 0.0, 1.0)
}
fn draw_bars(input, top, height, bg) {
let cmds = [];
if height <= 0 {
return cmds;
}
let width = input.width;
let bar_width = if width >= 80 { 2 } else { 1 };
let bars = width / bar_width;
let bar = 0;
while bar < bars {
let freq = to_float(bar) / to_float(bars);
let value = spectrum_value(freq, input);
let bar_height = to_int(clamp(value * to_float(height), 1.0, to_float(height)));
let fg = rgb(60 + (1.0 - freq) * 80, 160 + value * 95, 210 - freq * 110);
let x = bar * bar_width;
let y = top + height - bar_height;
let w = if bar_width > 1 && x + 1 < width { 2 } else { 1 };
if bar_height > 0 {
cmds.push(rect(x, y, w, bar_height, "#", fg, bg));
}
bar += 1;
}
cmds
}
fn append_all(cmds, more) {
for cmd in more {
cmds.push(cmd);
}
cmds
}
fn track_label(input) {
if input.track_artist != "" && input.track_title != "" {
input.track_artist + " - " + input.track_title
} else if input.track_title != "" {
input.track_title
} else {
input.track_artist
}
}
fn draw_track_badge(input, bg) {
let cmds = [];
let label = track_label(input);
if label == "" || input.width <= 8 || input.height <= 4 {
return cmds;
}
let max_text = input.width - 6;
let value = if label.len() > max_text {
label.sub_string(0, max_text)
} else {
label
};
let badge_width = min(value.len() + 4, input.width);
let x = (input.width - badge_width) / 2;
let y = input.height - 1;
let badge_bg = rgb(0, 30 + input.energy * 36, 38 + input.beat * 42);
let badge_fg = rgb(190 + input.treble * 45, 255, 235);
cmds.push(rect(x, y, badge_width, 1, " ", badge_fg, badge_bg));
cmds.push(text(x + 2, y, value, badge_fg, badge_bg));
cmds
}
fn render(input) {
let cmds = [];
let bg = rgb(0, 0, 0);
cmds.push(#{ op: "clear", bg: bg });
if input.width <= 0 || input.height <= 2 {
return cmds;
}
let content_height = input.height - 2;
let bars_height = if content_height > 12 { 8 } else { content_height / 3 };
let separator = if bars_height > 0 { 1 } else { 0 };
let scope_height = content_height - bars_height - separator;
cmds = append_all(cmds, draw_grid(input.width, scope_height, input.progress, input.energy, bg));
cmds = append_all(cmds, draw_scope(input, scope_height, bg));
if bars_height > 0 {
let sep_y = scope_height;
let sep = rgb(20, 68, 74);
cmds.push(hline(0, sep_y, input.width, "-", sep, bg));
cmds = append_all(cmds, draw_bars(input, sep_y + separator, bars_height, bg));
}
if input.show_clock {
let clock_bg = rgb(0, 26, 30);
let clock_fg = rgb(180, 255, 245);
cmds.push(text(1, 0, " " + input.clock + " ", clock_fg, clock_bg));
}
cmds = append_all(cmds, draw_track_badge(input, bg));
cmds
}
+57
View File
@@ -0,0 +1,57 @@
// name: Status braille histogram
// protocol: furumi-visualizer-v2
// surface: status
// revision: 2
//
// One-row waveform histogram. Input is decoded audio BEFORE output volume.
// The host freezes the last frame on pause, including custom scripts.
// Edit this file to customize it; only untouched bundled defaults upgrade.
// Each Braille character packs two independent four-dot vertical columns.
// "default" background retains the terminal's background color.
fn clamp(value, low, high) {
if value < low { low } else if value > high { high } else { value }
}
// Local RMS for one slice of the recent waveform. Method syntax avoids
// copying the complete sample array for every column.
fn level(index, columns, reference) {
let count = this.len();
if count == 0 { return 0; }
let start = index * count / columns;
let end = (index + 1) * count / columns;
let square = 0.0;
let total = 0;
for i in start..end {
square += this[i] * this[i];
total += 1;
}
let rms = if total > 0 { sqrt(square / to_float(total)) }
else { abs(this[start]) };
// Remove the near-silent baseline and spread useful levels over 0..4.
// No additive bass/energy/beat floor: quiet columns really become empty.
let normalized = clamp((rms / reference - 0.12) / 0.72, 0.0, 1.0);
to_int(normalized * 4.0 + 0.5)
}
fn render(input) {
let commands = [#{ op: "clear", bg: "default" }];
if input.width <= 0 || input.height <= 0 { return commands; }
let samples = input.samples;
let square = 0.0;
for sample in samples { square += sample * sample; }
let rms = if samples.len() > 0 { sqrt(square / to_float(samples.len())) } else { 0.0 };
// Adapt headroom to the current recording, with an absolute noise floor
// so silence/very quiet passages are never normalized into a full row.
let reference = if rms * 1.8 > 0.10 { rms * 1.8 } else { 0.10 };
let dots = ["⠀⢀⢠⢰⢸", "⡀⣀⣠⣰⣸", "⡄⣄⣤⣴⣼", "⡆⣆⣦⣶⣾", "⡇⣇⣧⣷⣿"];
let columns = input.width * 2;
for x in 0..input.width {
let left = samples.level(x * 2, columns, reference);
let right = samples.level(x * 2 + 1, columns, reference);
let glyph = dots[left].sub_string(right, 1);
commands.push(#{ op: "cell", x: x, y: 0, ch: glyph,
fg: 0x48c9c0, bg: "default" });
}
commands
}
+1315
View File
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,57 @@
// name: Status braille histogram
// protocol: furumi-visualizer-v2
// surface: status
//
// Always-on, one-row visualization. Edit this file to customize it; saved
// changes reload during playback. The host never overwrites an existing file.
// Same render(input) and draw commands as fullscreen scripts; height is 1.
// Audio bands and waveform amplitudes drive the bars (not a full FFT).
// Each Braille character packs two independent four-dot vertical columns.
// "default" background retains the terminal's background color.
// A method reads the waveform through `this`, avoiding an array copy for
// every column in this continuously running visualization.
fn level(index, columns, band, energy, beat) {
let wave = 0.0;
let count = this.len();
if count > 0 {
let start = index * count / columns;
let end = (index + 1) * count / columns;
let total = 0;
for i in start..end {
wave += abs(this[i]);
total += 1;
}
if total > 0 { wave /= to_float(total); }
else { wave = abs(this[start]); }
}
let value = band * 0.55 + wave * 0.8 + energy * 0.12 + beat * 0.18;
if value <= 0.01 { 0 }
else if value < 0.20 { 1 }
else if value < 0.40 { 2 }
else if value < 0.65 { 3 }
else { 4 }
}
fn render(input) {
let commands = [#{ op: "clear", bg: "default" }];
if input.width <= 0 || input.height <= 0 || input.paused { return commands; }
// Lookup table indexed by left/right bar heights, from the bottom up.
let dots = ["⠀⢀⢠⢰⢸", "⡀⣀⣠⣰⣸", "⡄⣄⣤⣴⣼", "⡆⣆⣦⣶⣾", "⡇⣇⣧⣷⣿"];
let columns = input.width * 2;
let samples = input.samples;
for x in 0..input.width {
let levels = [];
for side in 0..2 {
let index = x * 2 + side;
let phase = to_float(index) / to_float(columns);
let band = if phase < 0.33 { input.bass }
else if phase < 0.67 { input.mid } else { input.treble };
levels.push(samples.level(index, columns, band, input.energy, input.beat));
}
let glyph = dots[levels[0]].sub_string(levels[1], 1);
commands.push(#{ op: "cell", x: x, y: 0, ch: glyph,
fg: 0x48c9c0, bg: "default" });
}
commands
}
+583
View File
@@ -0,0 +1,583 @@
//! One-row surface: blocking preparation runs off the UI thread; views copy
//! only the prepared buffer. Uses the fullscreen engine and drawing commands.
use std::io::Write;
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex};
use std::time::Instant;
use ratatui::{
Frame,
buffer::Buffer,
layout::Rect,
style::{Color, Style},
widgets::Paragraph,
};
use tokio::sync::mpsc;
use unicode_width::UnicodeWidthStr;
use super::{
ScriptRuntime, features_from_state, input_map_with_features, render_commands_to_buffer,
};
use crate::app::{event::AppEvent, state::AppState};
const SOURCE: &str = include_str!("../visualizations/status/braille.rhai");
const LEGACY_SOURCE: &str = include_str!("fixtures/status_braille_v1.rhai");
pub fn script_path() -> anyhow::Result<PathBuf> {
Ok(super::visualizations_dir()?
.join("status")
.join("braille.rhai"))
}
pub(super) fn ensure_script() -> anyhow::Result<()> {
install_script_at(&script_path()?)
}
fn install_script_at(path: &Path) -> anyhow::Result<()> {
ensure_script_at(path)?;
// Upgrade only a byte-for-byte stock script, never a user's edited one.
if std::fs::metadata(path)?.len() == LEGACY_SOURCE.len() as u64
&& std::fs::read(path)? == LEGACY_SOURCE.as_bytes()
{
let mut replacement =
tempfile::NamedTempFile::new_in(path.parent().unwrap_or(Path::new(".")))?;
replacement.write_all(SOURCE.as_bytes())?;
replacement.as_file().sync_all()?;
if std::fs::read(path)? == LEGACY_SOURCE.as_bytes() {
replacement.persist(path)?;
}
}
Ok(())
}
fn ensure_script_at(path: &Path) -> anyhow::Result<()> {
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent)?;
}
match std::fs::OpenOptions::new()
.write(true)
.create_new(true)
.open(path)
{
Ok(mut file) => file.write_all(SOURCE.as_bytes())?,
Err(err) if err.kind() == std::io::ErrorKind::AlreadyExists => {}
Err(err) => return Err(err.into()),
}
Ok(())
}
pub fn visible(state: &AppState) -> bool {
state.player.playing && state.player.current.is_some() && state.device_playback.is_audio_owner()
}
pub fn playing(state: &AppState) -> bool {
visible(state) && !state.player.paused
}
fn source_input(width: u16, state: &AppState, elapsed: f64) -> rhai::Map {
// AnalyzedSource taps decoded audio before rodio's output volume. Keep
// those source levels intact; input.volume remains available as metadata.
let mut features = features_from_state(state, false);
features.elapsed_secs = elapsed;
input_map_with_features(Rect::new(0, 0, width, 1), state, features)
}
#[derive(Debug, Default)]
pub struct State {
target: Option<(u16, String)>,
generation: u64,
frame: Option<Buffer>,
error: Option<String>,
paused: bool,
}
impl State {
/// Invalidates in-flight results. A resize keeps the last frame until a
/// replacement arrives, including when playback is paused.
pub fn set_target(&mut self, target: Option<(u16, String)>) {
if self.target != target {
let same_track = self
.target
.as_ref()
.zip(target.as_ref())
.is_some_and(|(old, new)| old.1 == new.1);
self.target = target;
self.generation = self.generation.wrapping_add(1);
if !same_track {
self.frame = None;
}
self.error = None;
}
}
pub fn set_paused(&mut self, paused: bool) {
if self.paused != paused {
self.paused = paused;
self.generation = self.generation.wrapping_add(1);
}
}
pub fn apply(&mut self, ready: Ready) {
if ready.generation != self.generation || self.target.is_none() || self.paused {
return;
}
match ready.result {
Ok(frame) => {
self.frame = Some(frame);
self.error = None;
}
Err(error) => {
if self.error.as_ref() != Some(&error) {
tracing::warn!(%error, "status visualization failed");
}
self.frame = None;
self.error = Some(error);
}
}
}
pub fn draw(&self, frame: &mut Frame, area: Rect) {
if area.is_empty() {
return;
}
if let Some(buffer) = &self.frame {
if buffer.area.width == 0 {
return;
}
for x in 0..area.width {
let source_x =
usize::from(x) * usize::from(buffer.area.width) / usize::from(area.width);
if let Some(target) = frame.buffer_mut().cell_mut((area.x + x, area.y)) {
*target = buffer.content[source_x].clone();
}
}
} else if let Some(error) = &self.error {
frame.render_widget(
Paragraph::new(format!("viz: {error}")).style(Style::new().fg(Color::Red)),
area,
);
}
}
}
#[derive(Debug)]
pub struct Ready {
generation: u64,
result: Result<Buffer, String>,
}
/// One in-flight job at most: slow custom scripts drop ticks, never queue
/// frames or block input. AST caches are independent of fullscreen selection.
pub struct Renderer {
runtime: Arc<Mutex<ScriptRuntime>>,
started: Instant,
pub busy: bool,
}
impl Default for Renderer {
fn default() -> Self {
let mut runtime = ScriptRuntime::default();
runtime
.engine
.set_max_operations(200_000)
.set_max_array_size(8192)
.set_max_map_size(4096)
.set_max_string_size(32_768);
Self {
runtime: Arc::new(Mutex::new(runtime)),
started: Instant::now(),
busy: false,
}
}
}
impl Renderer {
pub fn request(&mut self, state: &AppState, tx: mpsc::UnboundedSender<AppEvent>) {
let Some((width, _)) = &state.status_visualizer.target else {
return;
};
if self.busy || !playing(state) || state.visualizer.active {
return;
}
self.busy = true;
let width = *width;
let generation = state.status_visualizer.generation;
let input = source_input(width, state, self.started.elapsed().as_secs_f64());
let runtime = Arc::clone(&self.runtime);
tokio::spawn(async move {
let result = tokio::task::spawn_blocking(move || {
let path = script_path().map_err(|e| e.to_string())?;
let mut runtime = runtime
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner);
if runtime.cached_path.is_none() {
// Retry initialization after a transient startup error.
install_script_at(&path).map_err(|e| e.to_string())?;
}
prepare(&mut runtime, &path, input, width)
})
.await
.unwrap_or_else(|err| Err(err.to_string()));
let _ = tx.send(AppEvent::StatusVisualizationReady(Ready {
generation,
result,
}));
});
}
}
fn prepare(
runtime: &mut ScriptRuntime,
path: &Path,
input: rhai::Map,
width: u16,
) -> Result<Buffer, String> {
if std::fs::metadata(path).map_err(|e| e.to_string())?.len() > 65_536 {
return Err("status script exceeds 64 KiB".into());
}
let commands = runtime.render(path, input)?;
if commands.len() > 4096 {
return Err("too many status drawing commands".into());
}
let area = Rect::new(0, 0, width, 1);
let mut buffer = Buffer::empty(area);
render_commands_to_buffer(&mut buffer, area, &commands);
// A user-supplied cell string must never spill into neighboring UI areas.
for cell in &mut buffer.content {
if cell.symbol().width() != 1 || cell.symbol().chars().any(char::is_control) {
cell.set_symbol(" ");
}
}
Ok(buffer)
}
#[cfg(test)]
mod tests {
use super::super::insert_float;
use super::*;
use ratatui::{Terminal, backend::TestBackend};
use rhai::{Array, Dynamic};
fn input(width: u16, level: f64) -> rhai::Map {
let mut input = source_input(width, &AppState::default(), 0.0);
for band in ["energy", "bass", "mid", "treble", "beat"] {
insert_float(&mut input, band, level);
}
input.insert(
"samples".into(),
(0..256)
.map(|index| {
Dynamic::from_float(level * (index as f64 * std::f64::consts::TAU / 64.0).sin())
})
.collect::<Array>()
.into(),
);
input
}
#[test]
fn histogram_uses_braille_and_real_levels_in_one_row() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("status/braille.rhai");
ensure_script_at(&path).unwrap();
let renderer = Renderer::default();
let mut runtime = renderer.runtime.lock().unwrap();
for width in [0, 1, 8, 60, 200] {
let quiet = prepare(&mut runtime, &path, input(width, 0.0), width).unwrap();
let loud = prepare(&mut runtime, &path, input(width, 1.0), width).unwrap();
assert_eq!(loud.area, Rect::new(0, 0, width, 1));
assert!(quiet.content.iter().all(|cell| cell.symbol() == "⠀"));
assert!(loud.content.iter().all(|cell| {
cell.symbol()
.chars()
.all(|ch| ('\u{2800}'..='\u{28ff}').contains(&ch))
&& cell.bg == Color::Reset
}));
if width > 0 {
assert_ne!(loud, quiet);
}
let mut paused = input(width, 1.0);
paused.insert("paused".into(), true.into());
assert_eq!(prepare(&mut runtime, &path, paused, width).unwrap(), loud);
}
}
#[test]
fn existing_user_script_survives_and_hot_reload_recovers_from_errors() {
let file = tempfile::NamedTempFile::new().unwrap();
let path = file.path();
let mut runtime = ScriptRuntime::default();
for (revision, symbol) in [(1, "A"), (2, "B"), (3, "bad"), (4, "C")] {
let source = if symbol == "bad" {
"fn render(".into()
} else {
format!(
"fn render(input) {{ [#{{ op: \"text\", x: 0, y: 0, text: \"{symbol}\" }}] }}"
)
};
std::fs::write(path, &source).unwrap();
file.as_file()
.set_times(std::fs::FileTimes::new().set_modified(
std::time::UNIX_EPOCH
+ std::time::Duration::from_secs(1_700_000_000 + revision),
))
.unwrap();
install_script_at(path).unwrap();
assert_eq!(std::fs::read_to_string(path).unwrap(), source);
let frame = prepare(&mut runtime, path, input(8, 0.0), 8);
if symbol == "bad" {
assert!(frame.is_err());
} else {
assert_eq!(frame.unwrap().content[0].symbol(), symbol);
}
}
}
#[test]
fn status_commands_are_clipped_and_cannot_spill_into_the_ui() {
let file = tempfile::NamedTempFile::new().unwrap();
std::fs::write(
file.path(),
r##"fn render(input) { [
#{ op: "rect", x: 0, y: 0, w: 65535, h: 65535, ch: "#" },
#{ op: "text", x: 0, y: 1, text: "outside" },
#{ op: "trace", x: 6, ys: [65535, 0, 65535], ch: "*" },
#{ op: "cell", x: 0, y: 0, ch: "界" },
#{ op: "cell", x: 1, y: 0, ch: "\n" },
#{ op: "cell", x: 2, y: 0, ch: "too long" }
] }"##,
)
.unwrap();
let buffer = prepare(&mut ScriptRuntime::default(), file.path(), input(8, 0.0), 8).unwrap();
assert!(buffer.content[..3].iter().all(|cell| cell.symbol() == " "));
let state = State {
frame: Some(buffer),
..State::default()
};
let mut terminal = Terminal::new(TestBackend::new(20, 4)).unwrap();
terminal
.draw(|frame| {
for cell in &mut frame.buffer_mut().content {
cell.set_symbol("x");
}
state.draw(frame, Rect::new(11, 3, 8, 1));
})
.unwrap();
let buffer = terminal.backend().buffer();
for y in 0..4 {
for x in 0..20 {
if y != 3 || !(11..19).contains(&x) {
assert_eq!(buffer[(x, y)].symbol(), "x");
}
}
}
}
#[test]
fn stale_frames_are_discarded_after_resize_track_change_or_stop() {
let mut state = State::default();
state.set_target(Some((8, "track-a".into())));
let generation = state.generation;
state.apply(Ready {
generation,
result: Ok(Buffer::empty(Rect::new(0, 0, 8, 1))),
});
assert!(state.frame.is_some());
for target in [
Some((12, "track-a".into())),
Some((12, "track-b".into())),
None,
] {
state.set_target(target);
let previous_frame = state.frame.clone();
state.apply(Ready {
generation,
result: Ok(Buffer::empty(Rect::new(0, 0, 8, 1))),
});
assert_eq!(state.frame, previous_frame);
}
assert!(state.frame.is_none());
}
#[test]
fn pause_freezes_the_last_frame_and_rejects_in_flight_work() {
let mut state = State::default();
state.set_target(Some((8, "track".into())));
let mut buffer = Buffer::empty(Rect::new(0, 0, 8, 1));
for cell in &mut buffer.content {
cell.set_symbol("⣤");
}
let generation = state.generation;
state.apply(Ready {
generation,
result: Ok(buffer.clone()),
});
state.set_paused(true);
state.apply(Ready {
generation,
result: Err("late error".into()),
});
state.apply(Ready {
generation: state.generation,
result: Ok(Buffer::empty(buffer.area)),
});
assert_eq!(state.frame.as_ref(), Some(&buffer));
// A paused resize adapts the frozen row instead of erasing it.
state.set_target(Some((12, "track".into())));
let mut terminal = Terminal::new(TestBackend::new(12, 1)).unwrap();
terminal
.draw(|frame| state.draw(frame, frame.area()))
.unwrap();
assert!(
terminal
.backend()
.buffer()
.content
.iter()
.all(|cell| cell.symbol() == "⣤")
);
let paused_generation = state.generation;
state.set_paused(false);
state.apply(Ready {
generation: paused_generation,
result: Err("stale pause".into()),
});
assert_eq!(state.frame.as_ref(), Some(&buffer));
state.apply(Ready {
generation: state.generation,
result: Ok(Buffer::empty(Rect::new(0, 0, 12, 1))),
});
assert_ne!(state.frame.as_ref(), Some(&buffer));
state.set_target(None);
assert!(state.frame.is_none());
}
#[test]
fn source_audio_input_is_independent_of_output_volume_and_pause() {
let file = tempfile::NamedTempFile::new().unwrap();
std::fs::write(file.path(), SOURCE).unwrap();
let mut state = AppState::default();
state.player.audio_analysis = crate::player::AudioAnalysisSnapshot {
energy: 0.8,
bass: 0.9,
mid: 0.6,
treble: 0.3,
beat: 0.5,
scope: (0..256).map(|i| (i as f64 * 0.13).sin() * 0.7).collect(),
..Default::default()
};
let mut runtime = ScriptRuntime::default();
let expected =
prepare(&mut runtime, file.path(), source_input(64, &state, 1.0), 64).unwrap();
for volume in [0, 1, 25, 80, 100] {
for paused in [false, true] {
state.player.volume = volume;
state.player.paused = paused;
let map = source_input(64, &state, 1.0);
for (key, level) in [
("energy", 0.8),
("bass", 0.9),
("mid", 0.6),
("treble", 0.3),
("beat", 0.5),
] {
assert_eq!(map[key].as_float().unwrap(), level);
}
assert_eq!(map["volume"].as_float().unwrap(), f64::from(volume) / 100.0);
assert_eq!(
prepare(&mut runtime, file.path(), map, 64).unwrap(),
expected
);
}
}
}
#[test]
fn loud_recordings_use_multiple_heights_instead_of_a_solid_row() {
let file = tempfile::NamedTempFile::new().unwrap();
let mut runtime = ScriptRuntime::default();
std::fs::write(file.path(), LEGACY_SOURCE).unwrap();
let old = prepare(&mut runtime, file.path(), input(64, 1.0), 64).unwrap();
assert!(old.content.iter().all(|cell| cell.symbol() == "⣿"));
install_script_at(file.path()).unwrap();
// A fresh runtime also models a restart installing the new default.
let mut runtime = ScriptRuntime::default();
let new = prepare(&mut runtime, file.path(), input(64, 1.0), 64).unwrap();
let symbols: std::collections::HashSet<_> =
new.content.iter().map(|cell| cell.symbol()).collect();
assert!(symbols.len() >= 4, "{symbols:?}");
assert!(
new.content
.iter()
.filter(|cell| cell.symbol() == "⣿")
.count()
< 32
);
assert!(new.content.iter().any(|cell| cell.symbol() == "⠀"));
// Compressed band/beat values alone must not create a filled baseline.
let mut silence = input(64, 1.0);
silence.insert(
"samples".into(),
(0..256)
.map(|_| Dynamic::from_float(0.001))
.collect::<Array>()
.into(),
);
let silent = prepare(&mut runtime, file.path(), silence, 64).unwrap();
assert!(silent.content.iter().all(|cell| cell.symbol() == "⠀"));
}
#[test]
fn only_the_untouched_previous_default_is_upgraded() {
let file = tempfile::NamedTempFile::new().unwrap();
std::fs::write(file.path(), LEGACY_SOURCE).unwrap();
install_script_at(file.path()).unwrap();
assert_eq!(std::fs::read_to_string(file.path()).unwrap(), SOURCE);
install_script_at(file.path()).unwrap();
assert_eq!(std::fs::read_to_string(file.path()).unwrap(), SOURCE);
for stock in [LEGACY_SOURCE, SOURCE] {
let custom = format!("{stock}\n// user customization\n");
std::fs::write(file.path(), &custom).unwrap();
install_script_at(file.path()).unwrap();
assert_eq!(std::fs::read_to_string(file.path()).unwrap(), custom);
}
}
#[test]
fn status_script_infinite_loop_hits_the_operation_limit() {
let file = tempfile::NamedTempFile::new().unwrap();
std::fs::write(file.path(), "fn render(input) { loop {} [] }").unwrap();
let renderer = Renderer::default();
let mut runtime = renderer.runtime.lock().unwrap();
let err = prepare(&mut runtime, file.path(), input(8, 0.0), 8).unwrap_err();
assert!(err.contains("operations"), "{err}");
}
#[test]
#[ignore = "manual benchmark: cargo test --release benchmark_status_visualizer -- --ignored --nocapture"]
fn benchmark_status_visualizer() {
let file = tempfile::NamedTempFile::new().unwrap();
std::fs::write(file.path(), SOURCE).unwrap();
let renderer = Renderer::default();
let mut runtime = renderer.runtime.lock().unwrap();
for width in [32, 64, 128] {
let mut times = Vec::new();
for tick in 0..230 {
let level = (f64::from(tick) * 0.13).sin() * 0.5 + 0.5;
let input = input(width, level);
let start = Instant::now();
let frame = prepare(&mut runtime, file.path(), input, width).unwrap();
std::hint::black_box(frame);
if tick >= 30 {
times.push(start.elapsed().as_secs_f64() * 1000.0);
}
}
times.sort_by(f64::total_cmp);
println!(
"status {width}x1: median={:.3}ms p95={:.3}ms max={:.3}ms",
times[99], times[189], times[199]
);
}
}
}
+23
View File
@@ -0,0 +1,23 @@
[package]
name = "block"
version = "0.1.6"
authors = ["Steven Sheldon"]
description = "Rust interface for Apple's C language extension of blocks."
keywords = ["blocks", "osx", "ios", "objective-c"]
readme = "README.md"
repository = "http://github.com/SSheldon/rust-block"
documentation = "http://ssheldon.github.io/rust-objc/block/"
license = "MIT"
exclude = [
".gitignore",
".travis.yml",
"travis_install.sh",
"travis_test.sh",
"tests-ios/**",
]
[dev-dependencies.objc_test_utils]
version = "0.0"
path = "test_utils"
+42
View File
@@ -0,0 +1,42 @@
Rust interface for Apple's C language extension of blocks.
For more information on the specifics of the block implementation, see
Clang's documentation: http://clang.llvm.org/docs/Block-ABI-Apple.html
## Invoking blocks
The `Block` struct is used for invoking blocks from Objective-C. For example,
consider this Objective-C function:
``` objc
int32_t sum(int32_t (^block)(int32_t, int32_t)) {
return block(5, 8);
}
```
We could write it in Rust as the following:
``` rust
unsafe fn sum(block: &Block<(i32, i32), i32>) -> i32 {
block.call((5, 8))
}
```
Note the extra parentheses in the `call` method, since the arguments must be
passed as a tuple.
## Creating blocks
Creating a block to pass to Objective-C can be done with the `ConcreteBlock`
struct. For example, to create a block that adds two `i32`s, we could write:
``` rust
let block = ConcreteBlock::new(|a: i32, b: i32| a + b);
let block = block.copy();
assert!(unsafe { block.call((5, 8)) } == 13);
```
It is important to copy your block to the heap (with the `copy` method) before
passing it to Objective-C; this is because our `ConcreteBlock` is only meant
to be copied once, and we can enforce this in Rust, but if Objective-C code
were to copy it twice we could have a double free.
+399
View File
@@ -0,0 +1,399 @@
/*!
A Rust interface for Objective-C blocks.
For more information on the specifics of the block implementation, see
Clang's documentation: http://clang.llvm.org/docs/Block-ABI-Apple.html
# Invoking blocks
The `Block` struct is used for invoking blocks from Objective-C. For example,
consider this Objective-C function:
``` objc
int32_t sum(int32_t (^block)(int32_t, int32_t)) {
return block(5, 8);
}
```
We could write it in Rust as the following:
```
# use block::Block;
unsafe fn sum(block: &Block<(i32, i32), i32>) -> i32 {
block.call((5, 8))
}
```
Note the extra parentheses in the `call` method, since the arguments must be
passed as a tuple.
# Creating blocks
Creating a block to pass to Objective-C can be done with the `ConcreteBlock`
struct. For example, to create a block that adds two `i32`s, we could write:
```
# use block::ConcreteBlock;
let block = ConcreteBlock::new(|a: i32, b: i32| a + b);
let block = block.copy();
assert!(unsafe { block.call((5, 8)) } == 13);
```
It is important to copy your block to the heap (with the `copy` method) before
passing it to Objective-C; this is because our `ConcreteBlock` is only meant
to be copied once, and we can enforce this in Rust, but if Objective-C code
were to copy it twice we could have a double free.
*/
#[cfg(test)]
mod test_utils;
use std::marker::PhantomData;
use std::mem;
use std::ops::{Deref, DerefMut};
use std::os::raw::{c_int, c_ulong, c_void};
use std::ptr;
#[repr(C)]
struct Class {
_private: [u8; 0],
}
#[cfg_attr(any(target_os = "macos", target_os = "ios"),
link(name = "System", kind = "dylib"))]
#[cfg_attr(not(any(target_os = "macos", target_os = "ios")),
link(name = "BlocksRuntime", kind = "dylib"))]
extern "C" {
static _NSConcreteStackBlock: Class;
fn _Block_copy(block: *const c_void) -> *mut c_void;
fn _Block_release(block: *const c_void);
}
/// Types that may be used as the arguments to an Objective-C block.
pub trait BlockArguments: Sized {
/// Calls the given `Block` with self as the arguments.
///
/// Unsafe because `block` must point to a valid `Block` and this invokes
/// foreign code whose safety the compiler cannot verify.
unsafe fn call_block<R>(self, block: *mut Block<Self, R>) -> R;
}
macro_rules! block_args_impl {
($($a:ident : $t:ident),*) => (
impl<$($t),*> BlockArguments for ($($t,)*) {
unsafe fn call_block<R>(self, block: *mut Block<Self, R>) -> R {
let invoke: unsafe extern "C" fn(*mut Block<Self, R> $(, $t)*) -> R = {
let base = block as *mut BlockBase<Self, R>;
mem::transmute((*base).invoke)
};
let ($($a,)*) = self;
invoke(block $(, $a)*)
}
}
);
}
block_args_impl!();
block_args_impl!(a: A);
block_args_impl!(a: A, b: B);
block_args_impl!(a: A, b: B, c: C);
block_args_impl!(a: A, b: B, c: C, d: D);
block_args_impl!(a: A, b: B, c: C, d: D, e: E);
block_args_impl!(a: A, b: B, c: C, d: D, e: E, f: F);
block_args_impl!(a: A, b: B, c: C, d: D, e: E, f: F, g: G);
block_args_impl!(a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H);
block_args_impl!(a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H, i: I);
block_args_impl!(a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H, i: I, j: J);
block_args_impl!(a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H, i: I, j: J, k: K);
block_args_impl!(a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H, i: I, j: J, k: K, l: L);
#[repr(C)]
struct BlockBase<A, R> {
isa: *const Class,
flags: c_int,
_reserved: c_int,
invoke: unsafe extern "C" fn(*mut Block<A, R>, ...) -> R,
}
/// An Objective-C block that takes arguments of `A` when called and
/// returns a value of `R`.
#[repr(C)]
pub struct Block<A, R> {
_base: PhantomData<BlockBase<A, R>>,
}
impl<A: BlockArguments, R> Block<A, R> where A: BlockArguments {
/// Call self with the given arguments.
///
/// Unsafe because this invokes foreign code that the caller must verify
/// doesn't violate any of Rust's safety rules. For example, if this block
/// is shared with multiple references, the caller must ensure that calling
/// it will not cause a data race.
pub unsafe fn call(&self, args: A) -> R {
args.call_block(self as *const _ as *mut _)
}
}
/// A reference-counted Objective-C block.
pub struct RcBlock<A, R> {
ptr: *mut Block<A, R>,
}
impl<A, R> RcBlock<A, R> {
/// Construct an `RcBlock` for the given block without copying it.
/// The caller must ensure the block has a +1 reference count.
///
/// Unsafe because `ptr` must point to a valid `Block` and must have a +1
/// reference count or it will be overreleased when the `RcBlock` is
/// dropped.
pub unsafe fn new(ptr: *mut Block<A, R>) -> Self {
RcBlock { ptr: ptr }
}
/// Constructs an `RcBlock` by copying the given block.
///
/// Unsafe because `ptr` must point to a valid `Block`.
pub unsafe fn copy(ptr: *mut Block<A, R>) -> Self {
let ptr = _Block_copy(ptr as *const c_void) as *mut Block<A, R>;
RcBlock { ptr: ptr }
}
}
impl<A, R> Clone for RcBlock<A, R> {
fn clone(&self) -> RcBlock<A, R> {
unsafe {
RcBlock::copy(self.ptr)
}
}
}
impl<A, R> Deref for RcBlock<A, R> {
type Target = Block<A, R>;
fn deref(&self) -> &Block<A, R> {
unsafe { &*self.ptr }
}
}
impl<A, R> Drop for RcBlock<A, R> {
fn drop(&mut self) {
unsafe {
_Block_release(self.ptr as *const c_void);
}
}
}
/// Types that may be converted into a `ConcreteBlock`.
pub trait IntoConcreteBlock<A>: Sized where A: BlockArguments {
/// The return type of the resulting `ConcreteBlock`.
type Ret;
/// Consumes self to create a `ConcreteBlock`.
fn into_concrete_block(self) -> ConcreteBlock<A, Self::Ret, Self>;
}
macro_rules! concrete_block_impl {
($f:ident) => (
concrete_block_impl!($f,);
);
($f:ident, $($a:ident : $t:ident),*) => (
impl<$($t,)* R, X> IntoConcreteBlock<($($t,)*)> for X
where X: Fn($($t,)*) -> R {
type Ret = R;
fn into_concrete_block(self) -> ConcreteBlock<($($t,)*), R, X> {
unsafe extern "C" fn $f<$($t,)* R, X>(
block_ptr: *mut ConcreteBlock<($($t,)*), R, X>
$(, $a: $t)*) -> R
where X: Fn($($t,)*) -> R {
let block = &*block_ptr;
(block.closure)($($a),*)
}
let f: unsafe extern "C" fn(*mut ConcreteBlock<($($t,)*), R, X> $(, $a: $t)*) -> R = $f;
unsafe {
ConcreteBlock::with_invoke(mem::transmute(f), self)
}
}
}
);
}
concrete_block_impl!(concrete_block_invoke_args0);
concrete_block_impl!(concrete_block_invoke_args1, a: A);
concrete_block_impl!(concrete_block_invoke_args2, a: A, b: B);
concrete_block_impl!(concrete_block_invoke_args3, a: A, b: B, c: C);
concrete_block_impl!(concrete_block_invoke_args4, a: A, b: B, c: C, d: D);
concrete_block_impl!(concrete_block_invoke_args5, a: A, b: B, c: C, d: D, e: E);
concrete_block_impl!(concrete_block_invoke_args6, a: A, b: B, c: C, d: D, e: E, f: F);
concrete_block_impl!(concrete_block_invoke_args7, a: A, b: B, c: C, d: D, e: E, f: F, g: G);
concrete_block_impl!(concrete_block_invoke_args8, a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H);
concrete_block_impl!(concrete_block_invoke_args9, a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H, i: I);
concrete_block_impl!(concrete_block_invoke_args10, a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H, i: I, j: J);
concrete_block_impl!(concrete_block_invoke_args11, a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H, i: I, j: J, k: K);
concrete_block_impl!(concrete_block_invoke_args12, a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H, i: I, j: J, k: K, l: L);
/// An Objective-C block whose size is known at compile time and may be
/// constructed on the stack.
#[repr(C)]
pub struct ConcreteBlock<A, R, F> {
base: BlockBase<A, R>,
descriptor: Box<BlockDescriptor<ConcreteBlock<A, R, F>>>,
closure: F,
}
impl<A, R, F> ConcreteBlock<A, R, F>
where A: BlockArguments, F: IntoConcreteBlock<A, Ret=R> {
/// Constructs a `ConcreteBlock` with the given closure.
/// When the block is called, it will return the value that results from
/// calling the closure.
pub fn new(closure: F) -> Self {
closure.into_concrete_block()
}
}
impl<A, R, F> ConcreteBlock<A, R, F> {
/// Constructs a `ConcreteBlock` with the given invoke function and closure.
/// Unsafe because the caller must ensure the invoke function takes the
/// correct arguments.
unsafe fn with_invoke(invoke: unsafe extern "C" fn(*mut Self, ...) -> R,
closure: F) -> Self {
ConcreteBlock {
base: BlockBase {
isa: &_NSConcreteStackBlock,
// 1 << 25 = BLOCK_HAS_COPY_DISPOSE
flags: 1 << 25,
_reserved: 0,
invoke: mem::transmute(invoke),
},
descriptor: Box::new(BlockDescriptor::new()),
closure: closure,
}
}
}
impl<A, R, F> ConcreteBlock<A, R, F> where F: 'static {
/// Copy self onto the heap as an `RcBlock`.
pub fn copy(self) -> RcBlock<A, R> {
unsafe {
let mut block = self;
let copied = RcBlock::copy(&mut *block);
// At this point, our copy helper has been run so the block will
// be moved to the heap and we can forget the original block
// because the heap block will drop in our dispose helper.
mem::forget(block);
copied
}
}
}
impl<A, R, F> Clone for ConcreteBlock<A, R, F> where F: Clone {
fn clone(&self) -> Self {
unsafe {
ConcreteBlock::with_invoke(mem::transmute(self.base.invoke),
self.closure.clone())
}
}
}
impl<A, R, F> Deref for ConcreteBlock<A, R, F> {
type Target = Block<A, R>;
fn deref(&self) -> &Block<A, R> {
unsafe { &*(&self.base as *const _ as *const Block<A, R>) }
}
}
impl<A, R, F> DerefMut for ConcreteBlock<A, R, F> {
fn deref_mut(&mut self) -> &mut Block<A, R> {
unsafe { &mut *(&mut self.base as *mut _ as *mut Block<A, R>) }
}
}
unsafe extern "C" fn block_context_dispose<B>(block: &mut B) {
// Read the block onto the stack and let it drop
ptr::read(block);
}
unsafe extern "C" fn block_context_copy<B>(_dst: &mut B, _src: &B) {
// The runtime memmoves the src block into the dst block, nothing to do
}
#[repr(C)]
struct BlockDescriptor<B> {
_reserved: c_ulong,
block_size: c_ulong,
copy_helper: unsafe extern "C" fn(&mut B, &B),
dispose_helper: unsafe extern "C" fn(&mut B),
}
impl<B> BlockDescriptor<B> {
fn new() -> BlockDescriptor<B> {
BlockDescriptor {
_reserved: 0,
block_size: mem::size_of::<B>() as c_ulong,
copy_helper: block_context_copy::<B>,
dispose_helper: block_context_dispose::<B>,
}
}
}
#[cfg(test)]
mod tests {
use test_utils::*;
use super::{ConcreteBlock, RcBlock};
#[test]
fn test_call_block() {
let block = get_int_block_with(13);
unsafe {
assert!(block.call(()) == 13);
}
}
#[test]
fn test_call_block_args() {
let block = get_add_block_with(13);
unsafe {
assert!(block.call((2,)) == 15);
}
}
#[test]
fn test_create_block() {
let block = ConcreteBlock::new(|| 13);
let result = invoke_int_block(&block);
assert!(result == 13);
}
#[test]
fn test_create_block_args() {
let block = ConcreteBlock::new(|a: i32| a + 5);
let result = invoke_add_block(&block, 6);
assert!(result == 11);
}
#[test]
fn test_concrete_block_copy() {
let s = "Hello!".to_string();
let expected_len = s.len() as i32;
let block = ConcreteBlock::new(move || s.len() as i32);
assert!(invoke_int_block(&block) == expected_len);
let copied = block.copy();
assert!(invoke_int_block(&copied) == expected_len);
}
#[test]
fn test_concrete_block_stack_copy() {
fn make_block() -> RcBlock<(), i32> {
let x = 7;
let block = ConcreteBlock::new(move || x);
block.copy()
}
let block = make_block();
assert!(invoke_int_block(&block) == 7);
}
}
+31
View File
@@ -0,0 +1,31 @@
extern crate objc_test_utils;
use {Block, RcBlock};
pub fn get_int_block_with(i: i32) -> RcBlock<(), i32> {
unsafe {
let ptr = objc_test_utils::get_int_block_with(i);
RcBlock::new(ptr as *mut _)
}
}
pub fn get_add_block_with(i: i32) -> RcBlock<(i32,), i32> {
unsafe {
let ptr = objc_test_utils::get_add_block_with(i);
RcBlock::new(ptr as *mut _)
}
}
pub fn invoke_int_block(block: &Block<(), i32>) -> i32 {
let ptr = block as *const _;
unsafe {
objc_test_utils::invoke_int_block(ptr as *mut _)
}
}
pub fn invoke_add_block(block: &Block<(i32,), i32>, a: i32) -> i32 {
let ptr = block as *const _;
unsafe {
objc_test_utils::invoke_add_block(ptr as *mut _, a)
}
}