7.0 KiB
Development
Project overview · Installation · Admin UI conventions
Architecture
Furumusic is written in Rust on the
Cot 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 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:
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:
FURUMUSIC_LASTFM_TEST_DATABASE_URL=postgres://user:pass@localhost/test_db \
cargo test lastfm_popularity -- --include-ignored
Access and sharing tests
Podcast regressions include browser-store tests in tests/podcasts.test.cjs and an
isolated PostgreSQL fixture for multiuser subscriptions, progress generations,
retention and administrator actions:
node --test tests/podcasts.test.cjs
FURU_PODCAST_RENDER_FIXTURE=1 cargo test renders_podcast_navigation_and_views
node tests/browser-podcast-ui.cjs
FURU_PODCAST_TEST_DATABASE_URL=postgresql://... cargo test podcasts -- --include-ignored
FURU_PODCAST_TEST_DATABASE_URL=postgresql://... cargo test admin_unicode_search -- --include-ignored
Use a disposable database. The PostgreSQL test creates and drops a unique schema;
its audio files use a unique temporary directory. Normal podcast tests need no network.
The podcast fixture includes real Frid v4 subscription operations, snapshot exchange,
offline unsubscribe replay, legacy-peer filtering, and private Unicode search. The
admin fixture exercises list counts, all three catalogue lists and the track picker
with Cyrillic and Greek searches. Use a PostgreSQL build with ICU support; running
these fixtures on a database created with locale C covers the locale regression.
The browser UI fixture checks direct list/detail hashes on first load and reload,
back navigation, RSS artwork and broken-image fallbacks, explicit subscriptions,
compact search cards and mobile layout. It uses isolated API fixtures with the
rendered application. Set PLAYWRIGHT_MODULE and CHROME_PATH as for the other
browser tests. Optional ALPINE_FIXTURE points to a local Alpine.js bundle for
offline browser runs; otherwise the page loads Alpine from its normal CDN.
The access regression suite uses a disposable migrated database and a local OIDC provider with signed tokens and PKCE:
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
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
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
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.