feat: Move generated app state to XDG state/cache dirs - #407
Conversation
chore: use xdg config path for user config chore: use xdg state path for last session chore: use xdg state path for histories chore: use xdg cache path for streaming cache chore: use xdg config path for runtime client auth config chore: update comments to not explicitly reference `~/.config/spotatui/` chore: show actual config file path in first run prompt
introduce a core state module for machine-managed app state that will move out of config.yml, including volume, shuffle, active source, announcement state, layout sizes, radio stations, and sync token. resolve the state file through the XDG state directory, save it atomically with private file permissions, and add focused round-trip and sanitization coverage.
Separate app-managed runtime state into state.yml while keeping config.yml for user-authored preferences and startup overrides.
Move Spotify OAuth token cache out of the config directory and into the XDG state directory while keeping client.yml as user configuration. Gate cache-dir path helpers behind the streaming feature and document the state/cache locations for history, token cache, and native streaming cache. Persist volume changes through runtime state and flush pending state saves before CLI command exit.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughSpotatui separates startup configuration from persisted runtime state. It adds XDG-aware config, cache, and state paths, migrates legacy data, and updates playback, layout, radio, UI, plugin, and documentation code. ChangesRuntime state migration
Estimated code review effort: 4 (Complex) | ~60 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (2)
src/core/plugin_api.rs (1)
423-429: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd regression coverage for the runtime-backed snapshot.
Test that changing
RuntimeStateupdates all five migrated fields whileUserConfig.behaviorremains unchanged. The new values are exposed to plugins throughsrc/infra/scripting/engine.rs.As per coding guidelines, behavior changes require adding or adjusting Rust tests.
Also applies to: 474-479
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/core/plugin_api.rs` around lines 423 - 429, Add Rust regression coverage for config_snapshot, verifying that changing RuntimeState updates all five migrated snapshot fields while UserConfig.behavior remains unchanged. Exercise the plugin-facing values exposed through the scripting engine path, and preserve existing behavior for the unchanged user configuration.Source: Coding guidelines
src/core/user_config.rs (1)
47-64: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winSame-named helper with different semantics than
state.rs'ssanitized_radio_stations.This one dedupes by URL;
crate::core::state's module-levelsanitized_radio_stations(used forRuntimeState/state.yml) doesn't. Two functions with the same name and near-identical purpose diverging in behavior is easy to lose track of during future edits.Consider extracting one shared helper (e.g. in
crate::core::state, taking a slice or iterator) and reusing it from bothuser_config.rsandstate.rs, so both call sites get the same trim/empty-filter/dedupe guarantees for free.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/core/user_config.rs` around lines 47 - 64, Consolidate the duplicated sanitized_radio_stations helpers by defining one shared implementation in crate::core::state and reusing it from both user_config.rs and state.rs. Ensure the shared helper consistently trims names and URLs, filters empty values, and deduplicates stations by URL, while preserving both callers’ existing behavior.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@examples/plugins/README.md`:
- Around line 24-35: Make XDG path handling consistent across all listed sites:
in examples/plugins/README.md lines 24-35 and the install commands in
examples/plugins/accent-cycler.lua lines 6-10,
examples/plugins/now-playing-webhook.lua lines 7-9, and
examples/plugins/queue-browser.lua lines 6-10, normalize relative
XDG_CONFIG_HOME values to the application fallback before creating or copying
files; document in docs/native-streaming.md lines 29-37 that both
XDG_CONFIG_HOME and XDG_CACHE_HOME must be absolute, and in docs/scripting.md
lines 9-10 and docs/themes.md lines 24-26 that XDG_CONFIG_HOME is honored only
when absolute.
In `@README.md`:
- Around line 222-230: Update the XDG documentation and installation examples to
state that XDG_CONFIG_HOME, XDG_STATE_HOME, and XDG_CACHE_HOME are used only
when set to absolute paths; unset or relative values must use the HOME-based
fallback. In README.md (222-230 and 329-336), PLUGINS.md (20-23),
docs/configuration.md (14-14), and docs/keybindings.md (40-41), revise the prose
and config_home migration calculation accordingly. In
examples/plugins/session-stats/main.lua (7-9),
examples/plugins/track-info-popup.lua (4-6), and
examples/plugins/track-notifier.lua (4-6), validate XDG_CONFIG_HOME as absolute
before using it for copying, otherwise use the fallback path.
In `@src/infra/queue/dispatch.rs`:
- Around line 95-98: Persist runtime state after each ChangeVolume handler
updates RuntimeState: add the established save operation in
src/infra/queue/dispatch.rs lines 95-98, src/infra/subsonic/dispatch.rs lines
120-125, and src/infra/youtube/dispatch.rs lines 122-126, while preserving the
existing volume updates and return behavior.
In `@src/infra/radio/dispatch.rs`:
- Around line 89-93: Update the IoEvent::ChangeVolume branch to call
schedule_state_save() after assigning runtime_state.volume_percent, ensuring the
changed volume is queued for persistence before returning true.
In `@src/runtime.rs`:
- Around line 1111-1129: Gate the compatibility assignments for volume_percent,
sidebar_width_percent, playbar_height_rows, and library_height_percent behind
should_save_initial_state so they run only during initial state creation.
Preserve values loaded from state.yml on subsequent launches, and keep saving
the resulting migrated runtime state through the existing state_path persistence
block.
In `@src/tui/handlers/resize.rs`:
- Around line 67-86: Update reset_layout to clamp the config-derived
playbar_height_rows value to MAX_PLAYBAR_ROWS, matching the limit enforced by
increase_playbar_height. Preserve the existing default fallback and state-save
behavior.
---
Nitpick comments:
In `@src/core/plugin_api.rs`:
- Around line 423-429: Add Rust regression coverage for config_snapshot,
verifying that changing RuntimeState updates all five migrated snapshot fields
while UserConfig.behavior remains unchanged. Exercise the plugin-facing values
exposed through the scripting engine path, and preserve existing behavior for
the unchanged user configuration.
In `@src/core/user_config.rs`:
- Around line 47-64: Consolidate the duplicated sanitized_radio_stations helpers
by defining one shared implementation in crate::core::state and reusing it from
both user_config.rs and state.rs. Ensure the shared helper consistently trims
names and URLs, filters empty values, and deduplicates stations by URL, while
preserving both callers’ existing behavior.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 9b4de3df-1b0b-4452-bc35-d12b5db9aaf5
📒 Files selected for processing (53)
PLUGINS.mdREADME.mddocs/configuration.mddocs/keybindings.mddocs/native-streaming.mddocs/scripting.mddocs/themes.mdexamples/plugins/README.mdexamples/plugins/accent-cycler.luaexamples/plugins/now-playing-webhook.luaexamples/plugins/queue-browser.luaexamples/plugins/session-stats/main.luaexamples/plugins/track-info-popup.luaexamples/plugins/track-notifier.luasrc/cli/plugin.rssrc/core/app.rssrc/core/config.rssrc/core/first_run.rssrc/core/layout.rssrc/core/mod.rssrc/core/paths.rssrc/core/persisted_playback.rssrc/core/plugin_api.rssrc/core/state.rssrc/core/user_config.rssrc/infra/history.rssrc/infra/local/dispatch.rssrc/infra/media_metadata.rssrc/infra/network/native_shuffle.rssrc/infra/network/playback.rssrc/infra/network/utils.rssrc/infra/player/events.rssrc/infra/player/streaming.rssrc/infra/queue/dispatch.rssrc/infra/radio/dispatch.rssrc/infra/radio/mod.rssrc/infra/scripting/engine.rssrc/infra/subsonic/dispatch.rssrc/infra/youtube/dispatch.rssrc/infra/youtube/playlists.rssrc/runtime.rssrc/tui/handlers/announcement_prompt.rssrc/tui/handlers/library.rssrc/tui/handlers/mod.rssrc/tui/handlers/mouse.rssrc/tui/handlers/playlist.rssrc/tui/handlers/resize.rssrc/tui/handlers/search_results.rssrc/tui/handlers/select_device.rssrc/tui/runner.rssrc/tui/ui/library.rssrc/tui/ui/lyrics.rssrc/tui/ui/player.rs
DinoLeung
changed the title
Document that XDG directory variables are honored only when set to absolute paths, with HOME-based fallbacks for unset or relative values. Update plugin install and migration snippets to mirror runtime path resolution.
Persist decoded-backend volume changes through scheduled runtime state saves. Apply configured volume and layout defaults only when the corresponding runtime state fields are missing, so saved state.yml values remain authoritative after startup. Clamp config-derived playbar height during layout reset and document the initial-default behavior.
Add regression coverage for config_snapshot and the Lua-facing spotatui.config() path to ensure migrated behavior fields come from RuntimeState without mutating UserConfig. Share radio station sanitization between runtime state and user config.
There was a problem hiding this comment.
- Free-source users get pushed into a forced Spotify OAuth flow on upgrade (inline on
src/runtime.rs). - Listening history is silently orphaned, along with
last_session.yml(inline onsrc/infra/history.rs). - The window for doing this migration later closes on the first config save (inline on
src/core/user_config.rs).
All three are covered by one startup shim, run before state::load:
- If
<state>/state.ymlis absent, deserialize the legacy keys off the rawconfig.ymlinto a smallLegacyRuntimeKeysstruct and seedPersistedRuntimeState(active_source,shuffle_enabled,seen_announcement_ids, plus the app-savedradio_stations). - For
.spotify_token_cache.json,last_session.yml,history/, andstreaming_cache/: if the new path is absent and the old one exists,fs::renameit, falling back to copy across filesystems.
Finding 3 is why this belongs in this PR rather than a follow-up: once save_config() runs once, the legacy keys are gone for good.
Non-blocking
Four more inline: an existing-user regression on in-app saved radio stations, blind-overwrite vs the read-modify-write that save_config does, state-dir permissions, and a Windows path separator nit. Plus:
- Two dedupe implementations for radio stations (
state::sanitized_radio_stationsuses aHashSet,radio::dispatch::merged_radio_stationsre-implements it with aVecscan). Tiny lists, so this is drift risk rather than perf. dismissed_announcementshas no reader onmaineither. Good moment to drop dead state rather than carry it into a new file format.- Volume now persists from three layers (
App::{increase,decrease,set}_volume, each decoded dispatcher, and nowNetwork::change_volume). Correct, just redundant. - No CHANGELOG entry, against a repo that keeps detailed prose entries for user-visible changes.
Thanks for taking this on, the config/state separation is overdue.
| app.set_status_message("Radio station has no stream URL".to_string(), 4); | ||
| return; | ||
| }; | ||
| if app.is_configured_radio_station_url(url) { |
There was a problem hiding this comment.
Existing-user regression, worth handling in the same shim.
Before this PR, F (favorite) wrote into behavior.radio_stations in config.yml. After it, everything in config.yml counts as configured, so this guard fires and refuses removal with "Radio station is configured in config.yml". Every station a user saved in-app now needs a manual file edit to remove.
The ownership model itself is good, and I like that the guard exists rather than failing silently. The issue is only the day-one transition: moving pre-existing config.yml stations into state.yml during migration would avoid it entirely.
|
Thanks for the thorough review, and apologies for an extra long PR. I did want to keep it short and focus on the state and cache decoupling, it quickly gets out of hand. Will be addressing them later in the week. |
|
Sorry this keeps growing, i know you've already done more rounds than you signed up for. If you'd rather hand any of it off, i'll push the fixes myself. |
|
Thanks man. I’m happy to take another pass at the changes, but if there’s another round after that, I’d be happy to hand the remaining fixes over to you. |
Resolved CHANGELOG.md conflict from upstream merge.
|
I've made another round of changes. I'll leave #407 (comment) and #407 (comment) to you, since I'm not confident I can make a set of changes there that would be up to the project's standard. Also, I found it funny that you read my intent here as making the project compatible with Home Manager configuration. |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
src/infra/player/streaming.rs (1)
1524-1574: 🩺 Stability & Availability | 🔵 TrivialMigration now preserves the Connect device identity; consider surfacing a failed migration to the user.
get_default_cache_pathnow callsmigrate_legacy_streaming_cache_if_unclaimedbefore returning the new cache path, andlegacy_streaming_cache_migration_preserves_connect_device_idconfirmsdevice_idandcredentials.jsonsurvive the move. This resolves the earlier concern that upgrading would silently register spotatui as a brand-new Spotify Connect device.One gap remains: when migration fails, the code only logs a warning and continues with the new, empty cache path. In that case the device still re-registers as new, the same user-visible symptom as before, just now triggered by a filesystem error instead of "always". Consider surfacing this failure through a status message at startup (once the runtime plumbing for it exists) instead of relying on a log line most users never see.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/infra/player/streaming.rs` around lines 1524 - 1574, Update get_default_cache_path to surface migration failures through the existing startup status-message mechanism once runtime plumbing is available, rather than only emitting log::warn. Preserve returning the new cache path, and include enough context in the user-visible message to indicate that legacy streaming cache migration failed.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@examples/plugins/accent-cycler.lua`:
- Line 6: Update the plugin installation commands to resolve XDG_CONFIG_HOME
only when it is absolute, otherwise falling back to $HOME/.config before
appending the Spotatui plugins directory. Apply this consistently in
examples/plugins/accent-cycler.lua lines 6-6,
examples/plugins/now-playing-webhook.lua lines 7-7,
examples/plugins/now-playing.lua lines 6-8,
examples/plugins/track-info-popup.lua lines 4-6, and
examples/plugins/track-notifier.lua lines 4-4.
---
Nitpick comments:
In `@src/infra/player/streaming.rs`:
- Around line 1524-1574: Update get_default_cache_path to surface migration
failures through the existing startup status-message mechanism once runtime
plumbing is available, rather than only emitting log::warn. Preserve returning
the new cache path, and include enough context in the user-visible message to
indicate that legacy streaming cache migration failed.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: fa2856cb-9ff8-433d-8782-befa86572e93
📒 Files selected for processing (20)
CHANGELOG.mdPLUGINS.mddocs/keybindings.mdexamples/plugins/README.mdexamples/plugins/accent-cycler.luaexamples/plugins/now-playing-webhook.luaexamples/plugins/now-playing.luaexamples/plugins/queue-browser.luaexamples/plugins/session-stats/main.luaexamples/plugins/track-info-popup.luaexamples/plugins/track-notifier.luasrc/core/app.rssrc/core/config.rssrc/core/migrations.rssrc/core/persisted_playback.rssrc/infra/history.rssrc/infra/player/streaming.rssrc/runtime.rssrc/tui/handlers/playlist.rssrc/tui/runner.rs
🚧 Files skipped from review as they are similar to previous changes (9)
- examples/plugins/session-stats/main.lua
- src/infra/history.rs
- CHANGELOG.md
- PLUGINS.md
- src/tui/runner.rs
- examples/plugins/README.md
- docs/keybindings.md
- examples/plugins/queue-browser.lua
- src/core/app.rs
A malformed state.yml wedged every future save: `save` re-reads the file before merging, so a single bad write surfaced a UI error on every volume nudge and never recovered. The save path now backs the unreadable file up to state.yml.bak, warns, and continues from defaults, mirroring the config.yml fallback. Genuine read failures still propagate so a transient error cannot overwrite good data with defaults. State and config writes shared a fixed .tmp name, so two processes could write the same temp file and rename each other's half-written bytes into place. Route both through one atomic helper that writes to a process-unique temp (pid plus a per-process counter) and removes it if the rename fails.
Address Codex review of the state-recovery change. A write truncated mid multibyte character leaves invalid UTF-8, which read_to_string reported as an I/O error and the save path propagated instead of healing. Read raw bytes and treat non-UTF-8 contents as a corrupt file, so it backs up and recovers like any other malformed state. The atomic write helper only removed its temp file when the rename failed; a failure during the write itself leaked the temp. Clean up on either failure since each attempt uses a fresh unique name.
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/core/user_config.rs (1)
832-837: 🗄️ Data Integrity & Integration | 🔴 Critical | 🏗️ Heavy liftFix config precedence for the optional startup overrides.
RuntimeState::default()andRuntimeState::apply_persisted()supply current/fallback runtime values, not config seeds. If config seeds these values, apply the config defaults toruntime_statebefore persisting on startup; otherwise runtime state cannot distinguish saved runtime values from config-started values.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/core/user_config.rs` around lines 832 - 837, The startup initialization flow for the optional overrides sidebar_width_percent, playbar_height_rows, and library_height_percent must apply configured seed values to runtime_state before persistence, rather than relying on RuntimeState::default() or RuntimeState::apply_persisted(). Update the relevant config-to-runtime initialization logic while preserving existing persisted runtime values as the higher-priority source.
🧹 Nitpick comments (1)
src/core/auth.rs (1)
118-118: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winUse
anyhow::Result<()>for this helper, or document the exception.
write_private_file_atomicis new code undersrc/**/*.rs, but it returnsstd::io::Result<()>. The path rule requiresanyhow::Result<T>and?for error propagation. Change the helper to the project error type, or confirm that low-level filesystem helpers are exempt.As per path instructions,
src/**/*.rsmust useanyhow::Result<T>and the?operator for error propagation.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/core/auth.rs` at line 118, Update write_private_file_atomic to return anyhow::Result<()> and preserve ?-based propagation for its filesystem operations, converting underlying I/O errors through anyhow as needed; only retain std::io::Result<()> if the project explicitly documents this low-level helper as exempt from the src/**/*.rs error-type rule.Source: Path instructions
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@src/core/user_config.rs`:
- Around line 832-837: The startup initialization flow for the optional
overrides sidebar_width_percent, playbar_height_rows, and library_height_percent
must apply configured seed values to runtime_state before persistence, rather
than relying on RuntimeState::default() or RuntimeState::apply_persisted().
Update the relevant config-to-runtime initialization logic while preserving
existing persisted runtime values as the higher-priority source.
---
Nitpick comments:
In `@src/core/auth.rs`:
- Line 118: Update write_private_file_atomic to return anyhow::Result<()> and
preserve ?-based propagation for its filesystem operations, converting
underlying I/O errors through anyhow as needed; only retain std::io::Result<()>
if the project explicitly documents this low-level helper as exempt from the
src/**/*.rs error-type rule.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: b4d2648c-273f-41d6-9727-491f51356ac3
📒 Files selected for processing (3)
src/core/auth.rssrc/core/state.rssrc/core/user_config.rs
🚧 Files skipped from review as they are similar to previous changes (1)
- src/core/state.rs
New code under src/ uses anyhow::Result and ?-based propagation; convert the atomic write helper's error type to match. Callers already add their own context or propagate through anyhow, so this only drops the io::Result outlier.
2 participants
Summary
Move generated runtime/app state out of the config directory and into XDG state/cache locations.
This separates user-authored configuration from app-generated state.
config.ymlremains suitable for hand editing or declarative management, while runtime changes such as volume, layout, active source, radio favorites, history, and token/cache files move to the appropriate XDG state/cache locations.$XDG_CONFIG_HOME/spotatui.state.yml, listening history, and Spotify OAuth token cache under$XDG_STATE_HOME/spotatui.$XDG_CACHE_HOME/spotatui/streaming_cache.Testing
cargo fmt --allcargo test --no-default-features --features telemetrycargo clippy --no-default-features --features telemetry -- -D warningscargo testcargo test --features all-sourcescargo clippy --features all-sources -- -D warningscargo checkAdditional notes
Existing config-dir app data is migrated on first use when the new target path does not already exist. This includes legacy runtime fields/radio favorites from
config.yml, listening history,last_session.yml, Spotify OAuth token caches, and native streaming credentials/audio cache.If a new state/cache target already exists, the legacy file or directory is left in place instead of being merged or overwritten; users may need to move or remove legacy files manually only in that conflict case.
Summary by CodeRabbit
New Features
Bug Fixes
Documentation