From 9b923851ae606d5dd8037def2b342058b600ce5f Mon Sep 17 00:00:00 2001 From: Aleksandr Bogomiakov Date: Wed, 18 Nov 2026 15:17:50 +0000 Subject: [PATCH] Fixed build. Reworked mobile admin UI --- Cargo.lock | 2 +- Cargo.toml | 6 + README.md | 331 +--- docs/admin-ui.md | 100 ++ docs/administration.md | 131 ++ docs/development.md | 122 ++ docs/setup.md | 57 + templates/admin/navigation.html | 25 + templates/admin/responsive.html | 193 +++ templates/admin/setup.html | 14 +- templates/admin/styles.html | 2024 ++++++++++++++++++++++ templates/admin/ui.html | 120 ++ templates/admin/v2.html | 2334 ++------------------------ tests/admin_metadata_repair.test.cjs | 3 +- tests/admin_statistics.test.cjs | 3 +- tests/admin_v2_reviews.test.cjs | 3 +- tests/browser-admin-responsive.cjs | 164 ++ 17 files changed, 3095 insertions(+), 2537 deletions(-) create mode 100644 docs/admin-ui.md create mode 100644 docs/administration.md create mode 100644 docs/development.md create mode 100644 docs/setup.md create mode 100644 templates/admin/navigation.html create mode 100644 templates/admin/responsive.html create mode 100644 templates/admin/styles.html create mode 100644 templates/admin/ui.html create mode 100644 tests/browser-admin-responsive.cjs diff --git a/Cargo.lock b/Cargo.lock index 0d27773..68a93ca 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1988,7 +1988,7 @@ checksum = "e6d5a32815ae3f33302d95fdcb2ce17862f8c65363dcfd29360480ba1001fc9c" [[package]] name = "furumusic" -version = "0.12.3" +version = "0.12.4" dependencies = [ "anyhow", "async-stream", diff --git a/Cargo.toml b/Cargo.toml index 2de0e9f..bbc8624 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,6 +4,12 @@ version = "0.12.4" edition = "2024" description = "Reusable web-app boilerplate: auth, OIDC/SSO, admin panel, user management, i18n, PostgreSQL" +# Unoptimized dependencies overflow macOS compact unwind's 24-bit DWARF offset +# (16 MiB of __eh_frame). Keep dependency code small while leaving application +# code unoptimized and retaining debug symbols, assertions and panic unwinding. +[profile.dev.package."*"] +opt-level = 1 + # macOS 27 rejects some stripped proc-macro dylibs with a misaligned LINKEDIT # string pool. Build scripts and proc macros are compile-time artifacts only. [profile.release.build-override] diff --git a/README.md b/README.md index eefd1c9..d5ecd5d 100644 --- a/README.md +++ b/README.md @@ -2,313 +2,52 @@ **Your library. Your users. Your network.** -Furumusic is a self-hosted, multi-user music server with a full web player and -support for the Furumi federated network. It turns a collection of music files -into a shared library that is available from any modern browser, while every -user keeps their own playlists, likes, listening history, and playback state. +Furumusic is a self-hosted music server with a full web player. Bring your music, +share a library with friends, and keep your own playlists, likes, and listening +history. Listen from a desktop or phone, or connect independent servers through +the Furumi federated network. -Music can be uploaded directly, imported from a `.torrent` file, or downloaded -from a magnet link. An optional AI-assisted import pipeline reads the available -tags and path information, reconstructs inconsistent metadata, finds artwork, -and organizes the result into artists, releases, and tracks. Uncertain matches -are kept for review instead of silently entering the library with bad data. +## What you can do -## Why Furumusic? +- **Listen anywhere.** Browse artists and releases, search your collection, build + queues, and manage playlists in a responsive web player. +- **Bring your collection.** Upload files and folders, or import music from + YouTube, torrents, and magnet links directly into your library or a playlist. +- **Organize your music.** Optional AI assistance recognizes metadata, finds + artwork, and helps repair messy releases. Review proposed changes before + applying them. +- **Share a song.** Send a track or queue link that anyone can play and download + without creating an account. +- **Welcome your people.** Use password login or SSO. Instance admins can approve + new users without needing access to the identity provider. +- **Discover more.** Find similar tracks and connect Last.fm for scrobbling. +- **Connect your players.** Pair trusted Furumi devices to synchronize playlists, + likes, playback state, and playback controls. +- **Join a network.** Discover and stream music from other participating peers + while keeping your own library independent. +- **Manage from any screen.** Review imports, manage users and background tasks, + and explore listening statistics in a desktop and mobile admin console. -Furumusic is for a household, a small community, or anyone who wants one music -library without handing it to a subscription service. The server owns the -catalog and media files; the browser is only the player. +AI assistance, federation, similarity search, Last.fm, and SSO are optional. +You choose which features to enable. -- one shared library with separate user accounts; -- a responsive web player with artists, releases, search, queue, and playlists; -- direct file uploads and imports from YouTube, torrent files, or magnet links; -- optional AI-assisted recognition and normalization of metadata; -- password login or OIDC/SSO with group grants and local administrator approval; -- public track, release, and queue links with scoped guest playback and downloads; -- optional federation without a central catalog or search service; -- trusted-device pairing, playback handoff, and synchronization between Furumi - players; -- Last.fm scrobbling and similarity-based discovery when configured. +## Quick start -Furumusic does not include music. Import only media you are allowed to store and -share. - -## Access and public sharing - -OIDC identifies accounts by issuer and subject. Matching admin groups take -precedence over matching user groups, and either SSO grant takes precedence over -a local role. Without matching groups (including an empty group configuration), -a new account waits for approval in **Admin → Users**. Any instance administrator -can approve it as a user or administrator. The waiting page updates automatically. -On subsequent SSO logins the group grant is refreshed: if it disappears, only an -independently assigned local role preserves access. Existing password accounts -keep their local roles; existing OIDC-only accounts retain their last SSO grant -until the next login, without receiving an implicit local approval. - -Sharing creates an unguessable `/share/{token}` link to a snapshot of track IDs, -including their order and repetitions. Guests and accounts awaiting approval can -play and download only the tracks in that snapshot, using the regular player. -They cannot browse the library, search, use recommendations, or write personal -history. Signing in from a share returns to that share; signing in from the root -shows only the approval page until access is granted. Track info offers a browser -download of the original audio file. The old radio implementation is removed. - -Migration `m_0053_local_approval_and_public_shares` deletes the old share records. -Old track/release/playlist URL routes are removed, with no compatibility layer. -Link expiry, cleanup, and revocation are not part of this implementation. - -The access regression suite uses a disposable migrated database and a local OIDC -provider with signed tokens and PKCE: - -```bash -node --test tests/*.test.cjs -FURU_ACCESS_TEST_DATABASE_URL=postgresql://... cargo test postgres_approval_survives_sso_changes_without_implicit_grants -- --ignored -# Fresh disposable instance on :18048, media root /tmp/furumi-access-media, -# PostgreSQL container furumi-access-test-pg, database furumi_access_test: -node tests/browser-access-sharing.cjs -``` - -The browser test requires Playwright (`PLAYWRIGHT_MODULE`) and Chrome -(`CHROME_PATH`), and uses local port 18049 for its OIDC provider. It checks -approval, SSO precedence and group removal, guest playback and downloads, -unauthorized track substitution, and desktop/mobile player behavior. - -## Importing music - -Users can add audio files from the web interface or ask the server to download -selected files from a torrent. Both routes feed the same import pipeline, so a -library remains consistent regardless of where its files came from. - -The importer combines embedded tags, filenames, folder structure, and existing -catalog context. With an OpenAI-compatible language model configured, it can -normalize artist and release names, separate featured artists, recover track -numbers and release types, and flag ambiguous results for a user to approve. -Cover art is taken from nearby image files or embedded artwork when available. - -The inbox and permanent library are separate directories. New files are first -processed in the inbox and are moved into the organized library only after -their metadata has been accepted. - -## Federation - -Federation is optional. Independent Furumusic and Furumi players that use the -same Network ID discover one another as a logical network. Each peer keeps its -own library and can continue working alone. - -When federation is enabled, local and remote artists, releases, and tracks can -appear in the same search and library views. Missing audio is streamed from an -available peer and can optionally be retained locally. Similarity search also -stays decentralized: embeddings and exact ranking remain on the instance that -owns the music. - -Trusted-device pairing is separate from public catalog discovery. It connects -a user's own Furumi players so likes, playlists, playback state, and control can -move between approved devices. - -## Build and run - -Furumusic requires PostgreSQL and a Rust toolchain with Rust 2024 edition -support. Create an empty database, provide its connection URL, and start the -server: +With Rust and PostgreSQL installed, create an empty database and start the server: ```bash export FURU_DATABASE_URL='postgresql://furumusic:password@127.0.0.1/furumusic' cargo run --release --locked ``` -Open to create the first administrator. -After setup, configure the inbox and library directories under **Admin → -Settings** before importing music. +Open to create your administrator account, +then configure the inbox and music library directories in **Admin → Settings**. -To listen on another address or port: +## Documentation -```bash -cargo run --release --locked -- -l 0.0.0.0:8000 -``` +- [Installation and configuration](docs/setup.md) +- [Using and administering Furumusic](docs/administration.md) +- [Development, architecture, and tests](docs/development.md) +- [Admin UI conventions](docs/admin-ui.md) -A Nix development shell is included for Linux and macOS: - -```bash -nix develop -cargo run --locked -``` - -The repository also contains a multi-stage `Dockerfile` for building a small -runtime image. A deployment must provide PostgreSQL plus persistent, writable -volumes for the inbox and music library. - -CI uses Rust 1.97.0 and cargo-chef 0.1.74 to cache compiled dependencies separately -from application sources. Buildx imports and exports intermediate layers through -`ultradesu/furumusic:buildcache` (`mode=max`). After the first build, changes to -source code, templates or prompts reuse the dependency layer when its recipe and -toolchain are unchanged. Both dependency and application builds use `--locked`. -Update the pinned build tools in `Dockerfile`; changing them rebuilds the cache. - -## Admin statistics - -The only admin interface is `/admin/v2`, also reachable from `/admin/`. -**Statistics** shows listening totals, a timeline, artist/track/release rankings, -and paginated history. Select an artist or track to see its listeners, then a -listener to see their history within the same filters. The **Users** list links -to each user's full statistics. - -Periods use UTC. Counts come from the synchronized `listen_event` history: a -natural finish, half of a track, or four minutes qualifies as a play. Interrupted -sessions under five seconds are not retained. Short retained sessions contribute -to listened time but not play counts. The source filter separates this instance -from synchronized devices. Artist rankings use recorded artist names, including -featured credits; the same artist is counted once per event. Existing history -remains available when its local audio file is deleted. Library and service -cards show current instance totals, independently of the listening filters. - -Migration `m_0051_add_listen_statistics_indexes` adds time and content indexes. -The old admin pages and `/admin/debug` are removed; first-run setup remains at -`/admin/setup`. - -Regression checks: - -```bash -node --test tests/*.test.cjs -cargo test admin:: -- --skip postgres_statistics_drilldown_and_pagination -# Use a disposable PostgreSQL; this test creates connection-local temporary tables. -FURU_STATISTICS_TEST_DATABASE_URL=postgresql://... cargo test postgres_statistics_drilldown_and_pagination -- --ignored -``` - -`tests/browser-statistics.cjs` additionally exercises a fresh disposable instance -at `FURU_TEST_URL` (default `http://127.0.0.1:3018`) and seeds the disposable Docker -container `furumi-statistics-test-pg`. It requires Playwright (or -`PLAYWRIGHT_MODULE`) and Chrome (or `CHROME_PATH`). Never point this test at a -live service. - -## Metadata Repair - -Admin → Library Tools provides a chat for editing the selected library resources. -Use **Show related**, then **Deselect all** to choose only the resources needed -for the task. Selecting a release includes its tracks; individual tracks can -then be unchecked to exclude them. Unselected artists remain read-only context -and their IDs can still be used in credits. Releases show their years; tracks -show their source release. - -The assistant sees the complete selected scope and replaces the proposed plan -after every clarification. Expand **Proposed changes** in the chat to review or -edit it before applying. Plans support moving tracks, creating releases, merging -releases, and deleting artists, releases, or tracks. Release deletion requires -explicit moves or deletion of all its tracks. Artist deletion detaches credits -and requires all credited releases and tracks to be included. - -Applied plans are transactional and can be undone from History. Metadata Repair -retains audio and artwork files for Undo. Undo refuses to overwrite subsequent -metadata, playback, or federation changes. - -```bash -node --test tests/admin_metadata_repair.test.cjs -cargo test admin::metadata_fix::tests -``` - -`tests/browser-metadata-repair.cjs` checks the chat and plan updates, a four-release -merge, deletion and restoration of tracks and artist credits, playlists, playback -queues, and undo conflicts. Run it only against a disposable instance and a -PostgreSQL container named `furumi-repair-test-pg`, with database -`furumi_repair_test`. Set `FURU_TEST_URL`, `FURU_REPAIR_TEST_PG`, `CHROME_PATH`, and -`PLAYWRIGHT_MODULE` as needed. It seeds `tests/metadata_repair_fixture.sql` after -creating the test administrator. Set `FURU_REPAIR_SKIP_SEED=1` for a seeded database. -With `FURU_REPAIR_TEST_MODEL=1`, it additionally checks the reported release-only -selection and full ordered tracklist against the configured model, applies and -undoes that plan, and verifies individual track exclusions. - -## Importing into playlists - -The player's download manager offers **Add downloads to a playlist** for file -and folder uploads and torrents, as well as YouTube. Choose an existing owned -playlist or create one before starting; leaving the choice empty imports only -into the library. Selected audio tracks are appended after processing or manual -approval, including files resolved to tracks already in the library. - -Migration `m_0052_add_import_playlist_destinations` persists the destination and -completion receipts. Retries and restarts retain the choice, avoid duplicates, -and do not re-add tracks subsequently removed by the user. A started batch keeps -its destination for its remaining files. - -```bash -node --test tests/import_playlists.test.cjs -# Disposable PostgreSQL; both tests use temporary tables. -FURU_IMPORT_TEST_DATABASE_URL=postgresql://... cargo test import_destinations -- --ignored -FURU_IMPORT_TEST_DATABASE_URL=postgresql://... cargo test torrent_playlist -- --ignored -``` - -`tests/browser-import-playlists.cjs` checks the file upload flow, database -reconciliation and the torrent picker on desktop and mobile. It requires a fresh -migrated instance with the import agent disabled at `FURU_TEST_URL` (default -`http://127.0.0.1:3019`), the disposable PostgreSQL container -`furumi-import-playlist-test-pg` with database `furumi_import_test`, and Playwright -and Chrome configured as above. It uses a local torrent preview fixture and -simulated imported tracks, without downloading external torrents. - -## Configuration - -Most settings can be changed from the administration interface. Every setting -also has a `FURU_`-prefixed environment variable; environment values take -priority over values stored in PostgreSQL. - -The settings needed for a useful first installation are: - -| Setting | Purpose | -| --- | --- | -| `FURU_DATABASE_URL` | PostgreSQL connection URL; required to run the service | -| `FURU_AGENT_INBOX_DIR` | Temporary inbox for uploads and downloaded files | -| `FURU_AGENT_STORAGE_DIR` | Permanent, organized music library | -| `FURU_AGENT_ENABLED` | Enables the background metadata import pipeline | -| `FURU_AGENT_LLM_URL` | Base URL of an OpenAI-compatible model server | -| `FURU_AGENT_LLM_MODEL` | Model used to recognize and normalize metadata | -| `FURU_FEDERATION_ENABLED` | Publishes the library and enables peer discovery | -| `FURU_FEDERATION_NETWORK_ID` | Joins peers with the same value into one logical network | - -AI recognition, federation, similarity search, Last.fm, and OIDC are optional. -A local password-authenticated server can be used without any of them. - -## Architecture - -Furumusic is written in Rust on the -[Cot](https://cot.rs) web framework. PostgreSQL stores the catalog, accounts, -playlists, configuration, and background-job state. Audio inspection uses -Symphonia, torrent downloads use librqbit, and the shared `music-dht`/Frid -protocol stack provides decentralized catalog search, media transfer, and -connected-device synchronization. - -The browser interface and JSON API are served by the same application. Import, -artwork, metadata enrichment, similarity indexing, and maintenance run as -durable background jobs rather than blocking playback requests. - -The `lastfm_popularity` job defaults to **light** mode: it requests popularity -only for tracks without a completed lookup or with a changed title or primary -artist. Both matches (including zero counts) and explicit Last.fm “Track not -found” results are skipped on subsequent light runs. HTTP errors, timeouts, -invalid responses, and other API errors remain eligible for retry. A failed -full refresh also makes that track eligible for the next light run. - -Choose **Full: refresh all visible tracks** in the task's admin parameters to -refresh existing statistics and retry previous misses. The options endpoint -`POST /admin/v2/api/jobs/lastfm_popularity/run-options` accepts -`{"refresh_existing": true}`; an empty object, scheduled runs, and the ordinary -run endpoint use light mode. Neither mode limits the number of tracks processed. -An authoritative miss clears current statistics while preserving their history. -The migration preserves existing popularity; legacy misses need one more lookup -because older versions did not persist them. - -## Contributing - -Bug reports, design discussions, and patches are welcome. Before submitting a -change, run: - -```bash -cargo fmt --all -- --check -cargo clippy --all-targets -- -D warnings -cargo test --all-targets -``` - -Last.fm database tests use temporary tables on a disposable PostgreSQL database: - -```bash -FURUMUSIC_LASTFM_TEST_DATABASE_URL=postgres://user:pass@localhost/test_db \ - cargo test lastfm_popularity -- --include-ignored -``` +Bug reports, ideas, and contributions are welcome. diff --git a/docs/admin-ui.md b/docs/admin-ui.md new file mode 100644 index 0000000..f07a5af --- /dev/null +++ b/docs/admin-ui.md @@ -0,0 +1,100 @@ +# Admin interface conventions + +[Project overview](../README.md) · [Development](development.md) + +The admin UI uses one Alpine application and shared layout primitives for every +section. Add features to this model rather than introducing a separate mobile +page or section-specific navigation. + +## Ownership + +- `templates/admin/navigation.html`: the single navigation tree, grouped into + Operations (reviews/tasks), Music (library/tools/statistics), and Instance + (users/settings). Existing hash routes remain the source of navigation state. +- `templates/admin/styles.html`: colors, typography and component appearance. +- `templates/admin/responsive.html`: shared layout, breakpoints, touch targets, + scroll regions, table cards and dialog sizing. Put responsive rules here. +- `templates/admin/ui.html`: viewport state, task tabs, settings navigation and + the shared overlay lifecycle. Business data and API actions remain in + `adminV2()` in `v2.html`. + +## Layout + +| Width | Navigation | Workspaces | Lists and dialogs | +| --- | --- | --- | --- | +| 1280 px and above | Persistent sidebar | Task list/detail/log side by side | Tables, centered bounded dialogs | +| 1024–1279 px | Persistent sidebar | Task tabs; settings in one column | Tables, bounded dialogs | +| 768–1023 px | Drawer | Task tabs; settings section picker | Tables in contained scroll areas | +| Below 768 px | Drawer | Single column | Table cards, full viewport dialogs | + +Keep CSS and `matchMedia` breakpoints in `ui.html` synchronized. The main panel +owns page scrolling. Use `minmax(0, 1fr)` and `min-width:0` for grid/flex children; +never restore a global minimum page width. The top bar stays available while +content scrolls. Navigation closes after route changes and when switching to +the desktop layout. It retains the active section and the existing URL routes. + +Use `.panel`, `.panel-head`, `.panel-title`, `.toolbar`, `.action-strip`, `.field` +and `.editor-grid` for new content. Toolbars wrap, inputs fill available space, +and mobile controls use 44 px touch targets and 16 px input text. Long identifiers, +paths and names must wrap. Avoid fixed column widths and inline grid definitions. + +For tabular lists, add `.responsive-table`, a `data-label` to every cell, and +`data-primary` to its identifying cell. Mobile CSS presents the same DOM as cards; +do not duplicate rows or hide actions. Give clickable row titles real buttons +using `.row-link`, so the operation also works with a keyboard. Dense comparisons, +charts and logs may scroll inside a named, keyboard-focusable region; horizontal +scrolling must never propagate to the page. Keep these exceptions intentional. + +Task tabs change presentation only: configuration and selected run stay in memory +when switching tabs or rotating the device. In settings, add a section ID and a +matching entry to the section picker. Put related controls in `.settings-grid`. + +## Dialogs + +Every dialog uses the same hierarchy and lifecycle: + +```html + +``` + +The helper locks the background with `inert`, moves focus into the dialog, traps +Tab/Shift+Tab, handles Escape through the existing close button, and restores +focus on close. Keep business rules in the close handler and disable that button +when closing is not allowed (for example, while merging). Nested pickers consume +Escape with `.stop` before the dialog handles it. Headers remain fixed while the +body scrolls; `.dialog-actions` keeps actions available at the bottom. On mobile, +dialogs use `100dvh` and safe-area padding. Reuse the helper for new overlays. + +For content gated by an asynchronous load inside an animated dialog, use +`:hidden="loading"` instead of nesting competing `x-show` transitions. Loading +and content should not both stay hidden when a response arrives during opening. + +## Verification + +Run `node --test tests/*.test.cjs` and build the Rust application (templates are +compiled into the binary). `tests/browser-admin-responsive.cjs` checks all seven +sections at 320, 390, 768, 1024 and 1440 px, navigation focus, task state retention, +settings jumps, all five dialogs, long content and landscape geometry. It uses a +disposable running instance with an admin and at least one release containing a +track; browser fixtures do not modify server data. Supply `FURU_TEST_URL`, +`FURU_TEST_USERNAME`, `FURU_TEST_PASSWORD`, `PLAYWRIGHT_MODULE`, and `CHROME_PATH` +as appropriate. Set `FURU_TEST_SCREENSHOTS` to inspect screenshots visually. + +Check both populated and empty views, long names/paths, loading states, keyboard +navigation, reachable Save/Close controls, and resize while an overlay is open. diff --git a/docs/administration.md b/docs/administration.md new file mode 100644 index 0000000..0b13bc8 --- /dev/null +++ b/docs/administration.md @@ -0,0 +1,131 @@ +# Using and administering Furumusic + +[Project overview](../README.md) · [Installation](setup.md) · [Development and tests](development.md) + +## Access and public sharing + +OIDC identifies accounts by issuer and subject. Matching admin groups take +precedence over matching user groups, and either SSO grant takes precedence over +a local role. Without matching groups (including an empty group configuration), +a new account waits for approval in **Admin → Users**. Any instance administrator +can approve it as a user or administrator. The waiting page updates automatically. +On subsequent SSO logins the group grant is refreshed: if it disappears, only an +independently assigned local role preserves access. Existing password accounts +keep their local roles; existing OIDC-only accounts retain their last SSO grant +until the next login, without receiving an implicit local approval. + +Sharing creates an unguessable `/share/{token}` link to a snapshot of track IDs, +including their order and repetitions. Guests and accounts awaiting approval can +play and download only the tracks in that snapshot, using the regular player. +They cannot browse the library, search, use recommendations, or write personal +history. Signing in from a share returns to that share; signing in from the root +shows only the approval page until access is granted. Track info offers a browser +download of the original audio file. The old radio implementation is removed. + +Migration `m_0053_local_approval_and_public_shares` deletes the old share records. +Old track/release/playlist URL routes are removed, with no compatibility layer. +Link expiry, cleanup, and revocation are not part of this implementation. + +## Importing music + +Users can add audio files from the web interface or ask the server to download +selected files from a torrent. Both routes feed the same import pipeline, so a +library remains consistent regardless of where its files came from. + +The importer combines embedded tags, filenames, folder structure, and existing +catalog context. With an OpenAI-compatible language model configured, it can +normalize artist and release names, separate featured artists, recover track +numbers and release types, and flag ambiguous results for a user to approve. +Cover art is taken from nearby image files or embedded artwork when available. + +The inbox and permanent library are separate directories. New files are first +processed in the inbox and are moved into the organized library only after +their metadata has been accepted. + +## Importing into playlists + +The player's download manager offers **Add downloads to a playlist** for file +and folder uploads and torrents, as well as YouTube. Choose an existing owned +playlist or create one before starting; leaving the choice empty imports only +into the library. Selected audio tracks are appended after processing or manual +approval, including files resolved to tracks already in the library. + +Migration `m_0052_add_import_playlist_destinations` persists the destination and +completion receipts. Retries and restarts retain the choice, avoid duplicates, +and do not re-add tracks subsequently removed by the user. A started batch keeps +its destination for its remaining files. + +## Federation + +Federation is optional. Independent Furumusic and Furumi players that use the +same Network ID discover one another as a logical network. Each peer keeps its +own library and can continue working alone. + +When federation is enabled, local and remote artists, releases, and tracks can +appear in the same search and library views. Missing audio is streamed from an +available peer and can optionally be retained locally. Similarity search also +stays decentralized: embeddings and exact ranking remain on the instance that +owns the music. + +Trusted-device pairing is separate from public catalog discovery. It connects +a user's own Furumi players so likes, playlists, playback state, and control can +move between approved devices. + +## Admin statistics + +The only admin interface is `/admin/v2`, also reachable from `/admin/`. +**Statistics** shows listening totals, a timeline, artist/track/release rankings, +and paginated history. Select an artist or track to see its listeners, then a +listener to see their history within the same filters. The **Users** list links +to each user's full statistics. + +Periods use UTC. Counts come from the synchronized `listen_event` history: a +natural finish, half of a track, or four minutes qualifies as a play. Interrupted +sessions under five seconds are not retained. Short retained sessions contribute +to listened time but not play counts. The source filter separates this instance +from synchronized devices. Artist rankings use recorded artist names, including +featured credits; the same artist is counted once per event. Existing history +remains available when its local audio file is deleted. Library and service +cards show current instance totals, independently of the listening filters. + +Migration `m_0051_add_listen_statistics_indexes` adds time and content indexes. +The old admin pages and `/admin/debug` are removed; first-run setup remains at +`/admin/setup`. + +## Metadata Repair + +Admin → Library Tools provides a chat for editing the selected library resources. +Use **Show related**, then **Deselect all** to choose only the resources needed +for the task. Selecting a release includes its tracks; individual tracks can +then be unchecked to exclude them. Unselected artists remain read-only context +and their IDs can still be used in credits. Releases show their years; tracks +show their source release. + +The assistant sees the complete selected scope and replaces the proposed plan +after every clarification. Expand **Proposed changes** in the chat to review or +edit it before applying. Plans support moving tracks, creating releases, merging +releases, and deleting artists, releases, or tracks. Release deletion requires +explicit moves or deletion of all its tracks. Artist deletion detaches credits +and requires all credited releases and tracks to be included. + +Applied plans are transactional and can be undone from History. Metadata Repair +retains audio and artwork files for Undo. Undo refuses to overwrite subsequent +metadata, playback, or federation changes. + +## Last.fm popularity updates + +The `lastfm_popularity` job defaults to **light** mode: it requests popularity +only for tracks without a completed lookup or with a changed title or primary +artist. Both matches (including zero counts) and explicit Last.fm “Track not +found” results are skipped on subsequent light runs. HTTP errors, timeouts, +invalid responses, and other API errors remain eligible for retry. A failed +full refresh also makes that track eligible for the next light run. + +Choose **Full: refresh all visible tracks** in the task's admin parameters to +refresh existing statistics and retry previous misses. The options endpoint +`POST /admin/v2/api/jobs/lastfm_popularity/run-options` accepts +`{"refresh_existing": true}`; an empty object, scheduled runs, and the ordinary +run endpoint use light mode. Neither mode limits the number of tracks processed. +An authoritative miss clears current statistics while preserving their history. +The migration preserves existing popularity; legacy misses need one more lookup +because older versions did not persist them. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..bad10bc --- /dev/null +++ b/docs/development.md @@ -0,0 +1,122 @@ +# Development + +[Project overview](../README.md) · [Installation](setup.md) · [Admin UI conventions](admin-ui.md) + +## Architecture + +Furumusic is written in Rust on the +[Cot](https://cot.rs) web framework. PostgreSQL stores the catalog, accounts, +playlists, configuration, and background-job state. Audio inspection uses +Symphonia, torrent downloads use librqbit, and the shared `music-dht`/Frid +protocol stack provides decentralized catalog search, media transfer, and +connected-device synchronization. + +The browser interface and JSON API are served by the same application. Import, +artwork, metadata enrichment, similarity indexing, and maintenance run as +durable background jobs rather than blocking playback requests. + +## Build profiles + +Development and test builds use basic optimization (`opt-level = 1`) for +dependencies to keep macOS unwind tables below the compact-unwind size limit. +Application code stays unoptimized; debug symbols, assertions and panic +unwinding remain enabled. The first build compiles dependencies with these +settings, then reuses them from Cargo's cache. Dependency stepping in a debugger +can be less exact because of optimization. Release settings are independent. + +See the [Cargo profile override documentation](https://doc.rust-lang.org/cargo/reference/profiles.html#overrides) for dependency-specific settings. + +## Container builds and CI + +CI uses Rust 1.97.0 and cargo-chef 0.1.74 to cache compiled dependencies separately +from application sources. Buildx imports and exports intermediate layers through +`ultradesu/furumusic:buildcache` (`mode=max`). After the first build, changes to +source code, templates or prompts reuse the dependency layer when its recipe and +toolchain are unchanged. Both dependency and application builds use `--locked`. +Update the pinned build tools in `Dockerfile`; changing them rebuilds the cache. + +## Contributing + +Bug reports, design discussions, and patches are welcome. Before submitting a +change, run: + +```bash +cargo fmt --all -- --check +cargo clippy --all-targets -- -D warnings +cargo test --all-targets +``` + +Last.fm database tests use temporary tables on a disposable PostgreSQL database: + +```bash +FURUMUSIC_LASTFM_TEST_DATABASE_URL=postgres://user:pass@localhost/test_db \ + cargo test lastfm_popularity -- --include-ignored +``` + +## Access and sharing tests + +The access regression suite uses a disposable migrated database and a local OIDC +provider with signed tokens and PKCE: + +```bash +node --test tests/*.test.cjs +FURU_ACCESS_TEST_DATABASE_URL=postgresql://... cargo test postgres_approval_survives_sso_changes_without_implicit_grants -- --ignored +# Fresh disposable instance on :18048, media root /tmp/furumi-access-media, +# PostgreSQL container furumi-access-test-pg, database furumi_access_test: +node tests/browser-access-sharing.cjs +``` + +The browser test requires Playwright (`PLAYWRIGHT_MODULE`) and Chrome +(`CHROME_PATH`), and uses local port 18049 for its OIDC provider. It checks +approval, SSO precedence and group removal, guest playback and downloads, +unauthorized track substitution, and desktop/mobile player behavior. + +## Statistics tests + +```bash +node --test tests/*.test.cjs +cargo test admin:: -- --skip postgres_statistics_drilldown_and_pagination +# Use a disposable PostgreSQL; this test creates connection-local temporary tables. +FURU_STATISTICS_TEST_DATABASE_URL=postgresql://... cargo test postgres_statistics_drilldown_and_pagination -- --ignored +``` + +`tests/browser-statistics.cjs` additionally exercises a fresh disposable instance +at `FURU_TEST_URL` (default `http://127.0.0.1:3018`) and seeds the disposable Docker +container `furumi-statistics-test-pg`. It requires Playwright (or +`PLAYWRIGHT_MODULE`) and Chrome (or `CHROME_PATH`). Never point this test at a +live service. + +## Metadata Repair tests + +```bash +node --test tests/admin_metadata_repair.test.cjs +cargo test admin::metadata_fix::tests +``` + +`tests/browser-metadata-repair.cjs` checks the chat and plan updates, a four-release +merge, deletion and restoration of tracks and artist credits, playlists, playback +queues, and undo conflicts. Run it only against a disposable instance and a +PostgreSQL container named `furumi-repair-test-pg`, with database +`furumi_repair_test`. Set `FURU_TEST_URL`, `FURU_REPAIR_TEST_PG`, `CHROME_PATH`, and +`PLAYWRIGHT_MODULE` as needed. It seeds `tests/metadata_repair_fixture.sql` after +creating the test administrator. Set `FURU_REPAIR_SKIP_SEED=1` for a seeded database. +With `FURU_REPAIR_TEST_MODEL=1`, it additionally checks the reported release-only +selection and full ordered tracklist against the configured model, applies and +undoes that plan, and verifies individual track exclusions. + +## Import destination tests + +```bash +node --test tests/import_playlists.test.cjs +# Disposable PostgreSQL; both tests use temporary tables. +FURU_IMPORT_TEST_DATABASE_URL=postgresql://... cargo test import_destinations -- --ignored +FURU_IMPORT_TEST_DATABASE_URL=postgresql://... cargo test torrent_playlist -- --ignored +``` + +`tests/browser-import-playlists.cjs` checks the file upload flow, database +reconciliation and the torrent picker on desktop and mobile. It requires a fresh +migrated instance with the import agent disabled at `FURU_TEST_URL` (default +`http://127.0.0.1:3019`), the disposable PostgreSQL container +`furumi-import-playlist-test-pg` with database `furumi_import_test`, and Playwright +and Chrome configured as above. It uses a local torrent preview fixture and +simulated imported tracks, without downloading external torrents. diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..7109c24 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,57 @@ +# Installation and configuration + +[Project overview](../README.md) · [Administration guide](administration.md) + +## Build and run + +Furumusic requires PostgreSQL and a Rust toolchain with Rust 2024 edition +support. Create an empty database, provide its connection URL, and start the +server: + +```bash +export FURU_DATABASE_URL='postgresql://furumusic:password@127.0.0.1/furumusic' +cargo run --release --locked +``` + +Open to create the first administrator. +After setup, configure the inbox and library directories under **Admin → +Settings** before importing music. + +To listen on another address or port: + +```bash +cargo run --release --locked -- -l 0.0.0.0:8000 +``` + +A Nix development shell is included for Linux and macOS: + +```bash +nix develop +cargo run --locked +``` + +The repository also contains a multi-stage `Dockerfile` for building a small +runtime image. A deployment must provide PostgreSQL plus persistent, writable +volumes for the inbox and music library. + +## Configuration + +Most settings can be changed from the administration interface. Every setting +also has a `FURU_`-prefixed environment variable; environment values take +priority over values stored in PostgreSQL. + +The settings needed for a useful first installation are: + +| Setting | Purpose | +| --- | --- | +| `FURU_DATABASE_URL` | PostgreSQL connection URL; required to run the service | +| `FURU_AGENT_INBOX_DIR` | Temporary inbox for uploads and downloaded files | +| `FURU_AGENT_STORAGE_DIR` | Permanent, organized music library | +| `FURU_AGENT_ENABLED` | Enables the background metadata import pipeline | +| `FURU_AGENT_LLM_URL` | Base URL of an OpenAI-compatible model server | +| `FURU_AGENT_LLM_MODEL` | Model used to recognize and normalize metadata | +| `FURU_FEDERATION_ENABLED` | Publishes the library and enables peer discovery | +| `FURU_FEDERATION_NETWORK_ID` | Joins peers with the same value into one logical network | + +AI recognition, federation, similarity search, Last.fm, and OIDC are optional. +A local password-authenticated server can be used without any of them. diff --git a/templates/admin/navigation.html b/templates/admin/navigation.html new file mode 100644 index 0000000..7965e97 --- /dev/null +++ b/templates/admin/navigation.html @@ -0,0 +1,25 @@ + diff --git a/templates/admin/responsive.html b/templates/admin/responsive.html new file mode 100644 index 0000000..fe31253 --- /dev/null +++ b/templates/admin/responsive.html @@ -0,0 +1,193 @@ + diff --git a/templates/admin/setup.html b/templates/admin/setup.html index c19d9ef..4bb76fc 100644 --- a/templates/admin/setup.html +++ b/templates/admin/setup.html @@ -5,13 +5,13 @@ {% block head_extra %} @@ -27,11 +27,11 @@
- + - + - +
diff --git a/templates/admin/styles.html b/templates/admin/styles.html new file mode 100644 index 0000000..fd63b58 --- /dev/null +++ b/templates/admin/styles.html @@ -0,0 +1,2024 @@ + diff --git a/templates/admin/ui.html b/templates/admin/ui.html new file mode 100644 index 0000000..007248a --- /dev/null +++ b/templates/admin/ui.html @@ -0,0 +1,120 @@ + diff --git a/templates/admin/v2.html b/templates/admin/v2.html index 5021e14..f98e866 100644 --- a/templates/admin/v2.html +++ b/templates/admin/v2.html @@ -3,2174 +3,33 @@ {% block title %}FuruMusic Admin v{{ version }}{% endblock title %} {% block head_extra %} - +{% include "admin/styles.html" %} +{% include "admin/responsive.html" %} {% endblock head_extra %} {% block content %} -
- - -
-
+
+
+

- - + - Player + Player
-
+
@@ -2235,7 +94,7 @@ tbody tr:hover {
- +
@@ -2250,24 +109,24 @@ tbody tr:hover { @@ -2293,8 +152,13 @@ tbody tr:hover {
-
-
+ +
+
Tasks @@ -2308,7 +172,7 @@ tbody tr:hover {
-
+
@@ -2320,26 +184,26 @@ tbody tr:hover {
Task