The ignored device-sync PostgreSQL test now also covers a handoff and a remote Next onto an episode with an unknown position (the relayed progress register supplies 1200 s and its generation), and checks that 0.12's operation types fail on a relayed podcast operation and read the log again after the documented cleanup statement, which the m_0055 backwards operation now shares. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
168 lines
7.8 KiB
Markdown
168 lines
7.8 KiB
Markdown
# 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.
|
|
|
|
## Connected devices and podcast queue items
|
|
|
|
Trusted-device sync uses the shared `music_dht::device_sync` types (no local
|
|
copies) and announces protocol version 4. The web player has no podcast
|
|
features yet, but it keeps every v4 element it receives:
|
|
|
|
- podcast operations stay in the operation log and are relayed to v4 devices
|
|
only; their registers and the podcast snapshot sections are merged with the
|
|
shared `music_dht::podcast` rules into `furumusic__fed_podcast_relay`
|
|
(opaque contract JSON) and returned in this server's snapshots;
|
|
- queue items that are not library tracks become external browser items
|
|
(`source` plus the verbatim `wire_track`), so podcast episodes and Jam
|
|
placeholders survive peer → server → browser → server → peer unchanged;
|
|
- `furumusic__playback_state.queue_items_json` stores the typed queue next to
|
|
`queue_json`. `queue_json` (library ids) is still written for rollback; the
|
|
typed value is used only while the legacy columns it recorded
|
|
(`queue_json`, `current_track_id`, `queue_position`) match the row. Jam
|
|
placeholders are never stored in a user's own queue.
|
|
- a browser that selects a podcast episode it cannot play does not know the
|
|
episode's position. It reports `position_unknown`, and the server sends the
|
|
resume position of the relayed progress register instead of 0. Jam
|
|
participant commands carry `jam_participant`; the host browser checks them
|
|
against its own queue.
|
|
|
|
Rolling back to 0.12 needs the podcast operations removed from the operation
|
|
log first; see "Rolling back to 0.12" in `administration.md`.
|
|
|
|
Everything sent to a device is gated by the version that device reported itself
|
|
(`profile_protocol_version`; relayed profiles only raise it). See the podcast
|
|
contract (`PODCASTS.md`) and `PLAYBACK_PROTOCOL.md` in the Frid repository.
|
|
|
|
```bash
|
|
cargo test devices:: queue_items podcast_relay queue_persistence
|
|
node --test tests/player_queue_sources.test.cjs
|
|
# Migrated disposable PostgreSQL (start the server against it once):
|
|
FURU_DEVICE_SYNC_TEST_DATABASE_URL=postgresql://... \
|
|
cargo test devices::postgres_tests -- --ignored
|
|
FURU_METADATA_FIX_TEST_DATABASE_URL=postgresql://... \
|
|
cargo test undo_accepts_playback_archives_written_before_the_typed_queue -- --ignored
|
|
```
|
|
|
|
`wire_compat_tests` compares the shared types with the private copies of
|
|
0.12.x byte for byte; `fixtures/v3_hello.golden.json` is the v3 shape. Rewrite
|
|
it only for a deliberate change, with `FURUMUSIC_BLESS_GOLDEN=1`.
|
|
|
|
## 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.
|