The Problem

Polaris’s source suffers from deep control‑flow nesting (max depth 8) in src/app/index.rs, src/app/scanner.rs and src/app/config.rs, making changes hard to reason about. Seventeen duplicated 6‑line blocks appear across src/app/index/collection.rs, src/app/scanner.rs, src/app.rs and src/server/error.rs, violating DRY. Two files are oversized—src/app/index/collection.rs at 961 LOC and src/server/axum/api.rs at 961 LOC—so a single edit ripples widely. These patterns increase cognitive load and risk introducing bugs when the codebase evolves.

What This Does

Polaris is a self‑hosted music‑streaming server written in Rust (56 Rust source files, cargo‑managed). The repo contains 164 files total: src/ holds the application logic, res/ holds assets and release scripts, and test-data/ provides fixtures for formats, playlists and artwork. Execution starts at src/main.rs:105 (entry point main) and src/main.rs:151 (async_main), which spawn the Axum HTTP server and initialise the index. The server stores metadata in an SQLite database (test-data/legacy_db_*.sqlite) and streams audio files from a configured mount directory. Outbound network calls (55 functions) enable features like remote demo access and DDNS updates; file I/O touches the local filesystem for scanning and playlist persistence.

How It Is Wired

The internal call graph resolves 687 edges among self‑defined functions. Five hub functions dominate traffic: complete_initial_setup (called from 61 places), fetch (55), login (49), setup_test (34) and login_admin (34). main reaches 17 downstream functions; try_from in src/server.rs:17 reaches 6. The entry point search (src/app/index.rs:291) fans out to 14 functions and is itself called from 13 call sites. Functions that leave the process boundary are complete_initial_setup, fetch and login, each making outbound network calls; can_persist_index and build in src/app/index.rs interact with the SQLite database. The widest blast‑radius functions are complete_initial_setup and fetch – a change to their signatures ripples through dozens of callers. File‑level responsibilities (by routed functions) are summarised by the analysis: src/app/config/user.rs handles user creation and admin flags; src/server/axum/api.rs builds the HTTP router and exposes settings endpoints; src/app/index/collection.rs provides collection queries; src/app/scanner.rs manages file‑watcher setup; src/app/index/search.rs implements fuzzy search.

How To Use It

Setup

git clone https://github.com/moses-y/polaris
cd polaris
cargo build --release   # produces ./target/release/polaris

Configuration The binary reads config.toml (generated on first run) and environment variables from .envrc (present at repo root). Key settings such as mount directories and user credentials are defined in src/app/config/user.rs and persisted under src/app/config/storage.rs. Running it

./target/release/polaris   # starts server on http://localhost:5050

Open http://localhost:5050/api-docs/ for the interactive OpenAPI spec, or point a Polaris client at the address to browse your collection.

Real‑World Use

A user runs polaris on a home server, points the mount directive at their /Music folder, and creates two local users via the UI (src/app/config/user.rs). Each user gets an isolated playlist store; the scanner (src/app/scanner.rs) watches the folder for new .flac/.mp3 files and updates the index automatically. Mobile clients connect to http://<server‑ip>:5050, browse albums/artists/genres, and stream audio with waveform visualisation. Admin users can adjust global settings (bitrate, dark‑mode palette) through src/server/axum/api.rs endpoints.

Code Health & Issues

Static analysis identified 12 issues:

  • 3 High – deep nesting in src/app/index.rs, src/app/scanner.rs, src/app/config.rs (max indentation 8).
  • 9 Medium – duplicated 6‑line blocks across src/app/index/collection.rs, src/app/scanner.rs, src/app.rs, src/server/error.rs; oversized files src/app/index/collection.rs (961 LOC) and src/server/axum/api.rs (961 LOC).

Beyond the measured block, the SDLC audit reveals:

  • High – Pin third‑party GitHub Actions to commit SHAs in .github/workflows (currently @v1 for setup-rust-toolchain, cargo, install-action, codecov).
  • Medium – Declare least‑privilege permissions: contents: read for GITHUB_TOKEN in build.yml (4 workflows have no declaration).
  • Medium – Enable Dependabot/Renovate; a dependabot.yml is absent.
  • Medium – Add dependency‑review or osv-scanner gate on PRs; no scan currently runs.
  • Low – Set timeout-minutes on workflow jobs (none declared; risk of overlapping runs).

The Bottom Line

Polaris delivers a capable, self‑hosted music‑streaming server with solid Rust performance and a rich feature set, but its maintainability suffers from deep nesting, duplicated logic and a few oversized modules. The CI pipeline is functional yet lacks action‑pinning, token‑permission discipline and automated dependency scanning—issues that should be addressed before production deployment. It is well‑suited for hobbyists or small teams wanting a flexible streaming stack, provided the code‑health items are resolved.