refactor(conf): replace eager dir creation with lazy Dir type (#5495)

* feat(conf): add Dir type with lazy directory creation

Introduces the Dir type that wraps a directory path string and defers
os.MkdirAll until the first call to Path() or MustPath(), using sync.Once
to ensure the creation happens exactly once. Implements fmt.Stringer,
encoding.TextMarshaler, and encoding.TextUnmarshaler for config integration.
Includes Ginkgo/Gomega tests covering all methods and error paths.

* refactor(conf): replace eager dir creation with lazy Dir type

Change DataFolder, CacheFolder, Plugins.Folder, and Backup.Path from
string to Dir. Remove all os.MkdirAll calls from Load() so directories
are created lazily on first Path()/MustPath() call. Artwork folder
creation was already handled at point-of-use in image_upload.go.

Add SnapshotConfig() to conf package for safe test config save/restore
that avoids copying sync.Once inside Dir fields. Fix copy-lock vet
warning in nativeapi/config.go by marshalling pointer instead of value.

* refactor(conf): migrate tests and db init to lazy Dir type

Update all test files to use conf.NewDir() for Dir field assignments.
Ensure DataFolder is created lazily when the database is first opened
in db.Db(). Remove eager directory creation from conf.Load() tests.

* fix(conf): address review findings for Dir type

- Use os.ModePerm for DataFolder/CacheFolder (was 0700, should match
  original behavior). Add NewDirWithPerm for PluginsFolder (0700).
- Use Path() instead of MustPath() in db.Prune() to avoid logFatal
  from background cron job.
- Panic on marshal/unmarshal errors in SnapshotConfig (test helper).
- Clean up redundant String()/MustPath() calls in plugin manager.
- Remove dead code in dir_test.go.

Signed-off-by: Deluan <deluan@navidrome.org>

* fix(conf): add GoString to Dir for clean config dump output

Implement fmt.GoStringer on Dir so pretty.Sprintf shows the path
string instead of internal struct fields (sync.Once, perm, err).
Also add TODO comment to configtest about removing the indirection.

* fix(dir): improve error logging in MustPath method

Signed-off-by: Deluan <deluan@navidrome.org>

* refactor(tests): remove redundant tests for unwritable DataFolder and CacheFolder

Signed-off-by: Deluan <deluan@navidrome.org>

* fix(conf): address PR review feedback

- Ensure Plugins.Folder always uses 0700, even when user-configured
  (previously only the derived default got restrictive permissions).
- Create LogFile parent directory before opening, so LogFile paths
  inside a not-yet-created DataFolder work correctly.

---------

Signed-off-by: Deluan <deluan@navidrome.org>

cmd/backup.go

@@ -75,7 +75,7 @@ var (
 
 func runBackup(ctx context.Context) {
 	if backupDir != "" {
-		conf.Server.Backup.Path = backupDir
+		conf.Server.Backup.Path = conf.NewDir(backupDir)
 	}
 
 	idx := strings.LastIndex(conf.Server.DbPath, "?")
@@ -104,7 +104,7 @@ func runBackup(ctx context.Context) {
 
 func runPrune(ctx context.Context) {
 	if backupDir != "" {
-		conf.Server.Backup.Path = backupDir
+		conf.Server.Backup.Path = conf.NewDir(backupDir)
 	}
 
 	if backupCount != -1 {

cmd/svc.go

@@ -76,13 +76,13 @@ var svcInstance = sync.OnceValue(func() service.Service {
 	options["Restart"] = "on-failure"
 	options["SuccessExitStatus"] = "1 2 8 SIGKILL"
 	options["UserService"] = false
-	options["LogDirectory"] = conf.Server.DataFolder
+	options["LogDirectory"] = conf.Server.DataFolder.String()
 	options["SystemdScript"] = systemdScript
 	if conf.Server.LogFile != "" {
 		options["LogOutput"] = false
 	} else {
 		options["LogOutput"] = true
-		options["LogDirectory"] = conf.Server.DataFolder
+		options["LogDirectory"] = conf.Server.DataFolder.String()
 	}
 	svcConfig := &service.Config{
 		UserName:    installUser,
@@ -131,11 +131,11 @@ func buildInstallCmd() *cobra.Command {
 		println("Installing service with:")
 		println("  working directory: " + executablePath())
 		println("  music folder:      " + conf.Server.MusicFolder)
-		println("  data folder:       " + conf.Server.DataFolder)
+		println("  data folder:       " + conf.Server.DataFolder.String())
 		if conf.Server.LogFile != "" {
 			println("  log file:          " + conf.Server.LogFile)
 		} else {
-			println("  logs folder:       " + conf.Server.DataFolder)
+			println("  logs folder:       " + conf.Server.DataFolder.String())
 		}
 		if cfgFile != "" {
 			conf.Server.ConfigFile, err = filepath.Abs(cfgFile)

conf/configtest/configtest.go

@@ -2,9 +2,7 @@ package configtest
 
 import "github.com/navidrome/navidrome/conf"
 
+// TODO Remove this redirection and call SnapshotConfig directly from tests
 func SetupConfig() func() {
-	oldValues := *conf.Server
-	return func() {
-		conf.Server = &oldValues
-	}
+	return conf.SnapshotConfig()
 }

conf/configuration.go

@@ -2,6 +2,7 @@ package conf
 
 import (
 	"cmp"
+	"encoding/json"
 	"fmt"
 	"net/url"
 	"os"
@@ -14,6 +15,7 @@ import (
 	"github.com/bmatcuk/doublestar/v4"
 	"github.com/dustin/go-humanize"
 	"github.com/go-viper/encoding/ini"
+	"github.com/go-viper/mapstructure/v2"
 	"github.com/kr/pretty"
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/log"
@@ -29,8 +31,8 @@ type configOptions struct {
 	UnixSocketPerm                  string
 	EnforceNonRootUser              bool
 	MusicFolder                     string
-	DataFolder                      string
-	CacheFolder                     string
+	DataFolder                      Dir
+	CacheFolder                     Dir
 	DbPath                          string
 	LogLevel                        string
 	LogFile                         string
@@ -229,7 +231,7 @@ type jukeboxOptions struct {
 
 type backupOptions struct {
 	Count    int
-	Path     string
+	Path     Dir
 	Schedule string
 }
 
@@ -247,7 +249,7 @@ type inspectOptions struct {
 
 type pluginsOptions struct {
 	Enabled    bool
-	Folder     string
+	Folder     Dir
 	CacheSize  string
 	AutoReload bool
 	LogLevel   string
@@ -287,6 +289,22 @@ var (
 	hooks  []func()
 )
 
+// SnapshotConfig returns a function that restores Server to its current state.
+// Uses JSON round-tripping so Dir fields get fresh sync.Once values.
+func SnapshotConfig() func() {
+	snapshot, err := json.Marshal(Server)
+	if err != nil {
+		panic(fmt.Sprintf("SnapshotConfig: marshal failed: %v", err))
+	}
+	return func() {
+		var restored configOptions
+		if err := json.Unmarshal(snapshot, &restored); err != nil {
+			panic(fmt.Sprintf("SnapshotConfig: unmarshal failed: %v", err))
+		}
+		Server = &restored
+	}
+}
+
 func LoadFromFile(confFile string) {
 	viper.SetConfigFile(confFile)
 	err := viper.ReadInConfig()
@@ -307,7 +325,13 @@ func Load(noConfigDump bool) {
 	mapDeprecatedOption("CoverJpegQuality", "CoverArtQuality")
 	mapDeprecatedOption("SimilarSongsMatchThreshold", "Matcher.FuzzyThreshold")
 
-	err := viper.Unmarshal(&Server)
+	err := viper.Unmarshal(&Server, viper.DecodeHook(
+		mapstructure.ComposeDecodeHookFunc(
+			mapstructure.TextUnmarshallerHookFunc(),
+			mapstructure.StringToTimeDurationHookFunc(),
+			mapstructure.StringToSliceHookFunc(","),
+		),
+	))
 	if err != nil {
 		logFatal("Error parsing config:", err)
 	}
@@ -317,48 +341,28 @@ func Load(noConfigDump bool) {
 		logFatal(err)
 	}
 
-	err = os.MkdirAll(Server.DataFolder, os.ModePerm)
-	if err != nil {
-		logFatal("Error creating data path:", err)
-	}
-
-	if Server.CacheFolder == "" {
-		Server.CacheFolder = filepath.Join(Server.DataFolder, "cache")
-	}
-	err = os.MkdirAll(Server.CacheFolder, os.ModePerm)
-	if err != nil {
-		logFatal("Error creating cache path:", err)
-	}
-
-	err = os.MkdirAll(filepath.Join(Server.DataFolder, consts.ArtworkFolder), os.ModePerm)
-	if err != nil {
-		logFatal("Error creating artwork path:", err)
+	if Server.CacheFolder.String() == "" {
+		Server.CacheFolder = NewDir(filepath.Join(Server.DataFolder.String(), "cache"))
 	}
 
 	if Server.Plugins.Enabled {
-		if Server.Plugins.Folder == "" {
-			Server.Plugins.Folder = filepath.Join(Server.DataFolder, "plugins")
-		}
-		err = os.MkdirAll(Server.Plugins.Folder, 0700)
-		if err != nil {
-			logFatal("Error creating plugins path:", err)
+		if Server.Plugins.Folder.String() == "" {
+			Server.Plugins.Folder = NewDirWithPerm(filepath.Join(Server.DataFolder.String(), "plugins"), 0700)
+		} else {
+			Server.Plugins.Folder = NewDirWithPerm(Server.Plugins.Folder.String(), 0700)
 		}
 	}
 
 	Server.ConfigFile = viper.GetViper().ConfigFileUsed()
 	if Server.DbPath == "" {
-		Server.DbPath = filepath.Join(Server.DataFolder, consts.DefaultDbPath)
-	}
-
-	if Server.Backup.Path != "" {
-		err = os.MkdirAll(Server.Backup.Path, os.ModePerm)
-		if err != nil {
-			logFatal("Error creating backup path:", err)
-		}
+		Server.DbPath = filepath.Join(Server.DataFolder.String(), consts.DefaultDbPath)
 	}
 
 	out := os.Stderr
 	if Server.LogFile != "" {
+		if mkErr := os.MkdirAll(filepath.Dir(Server.LogFile), os.ModePerm); mkErr != nil {
+			logFatal(fmt.Sprintf("Error creating log file directory: %s", mkErr.Error()))
+		}
 		out, err = os.OpenFile(Server.LogFile, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
 		if err != nil {
 			logFatal(fmt.Sprintf("Error opening log file %s: %s", Server.LogFile, err.Error()))
@@ -636,7 +640,7 @@ func validateScanSchedule() error {
 }
 
 func validateBackupSchedule() error {
-	if Server.Backup.Path == "" || Server.Backup.Schedule == "" || Server.Backup.Count == 0 {
+	if Server.Backup.Path.String() == "" || Server.Backup.Schedule == "" || Server.Backup.Count == 0 {
 		Server.Backup.Schedule = ""
 		return nil
 	}

conf/configuration_test.go

@@ -186,27 +186,12 @@ var _ = Describe("Configuration", func() {
 			}).To(PanicWith(ContainSubstring("Error reading config file")))
 		})
 
-		It("is called when DataFolder is not writable", func() {
-			viper.SetDefault("datafolder", invalidPath)
-			Expect(func() {
-				conf.Load(true)
-			}).To(PanicWith(ContainSubstring("Error creating data path")))
-		})
-
-		It("is called when CacheFolder is not writable", func() {
-			viper.SetDefault("datafolder", GinkgoT().TempDir())
-			viper.SetDefault("cachefolder", invalidPath)
-			Expect(func() {
-				conf.Load(true)
-			}).To(PanicWith(ContainSubstring("Error creating cache path")))
-		})
-
 		It("is called when LogFile path is not writable", func() {
 			viper.SetDefault("datafolder", GinkgoT().TempDir())
 			viper.SetDefault("logfile", filepath.Join(invalidPath, "log.txt"))
 			Expect(func() {
 				conf.Load(true)
-			}).To(PanicWith(ContainSubstring("Error opening log file")))
+			}).To(PanicWith(ContainSubstring("Error creating log file directory")))
 		})
 
 		It("is called when BaseURL is invalid", func() {

conf/dir.go

@@ -0,0 +1,76 @@
+package conf
+
+import (
+	"fmt"
+	"os"
+	"sync"
+)
+
+// Dir wraps a directory path and lazily creates the directory on first use.
+// The directory is created at most once; if creation fails, the error is
+// permanently cached (sync.Once semantics). Dir is not safe for mutation
+// after Path() has been called.
+type Dir struct {
+	path string
+	perm os.FileMode
+	once sync.Once
+	err  error
+}
+
+// NewDir creates a new Dir with the given path and default permissions (os.ModePerm).
+func NewDir(path string) Dir {
+	return Dir{path: path, perm: os.ModePerm}
+}
+
+// NewDirWithPerm creates a new Dir with the given path and permissions.
+func NewDirWithPerm(path string, perm os.FileMode) Dir {
+	return Dir{path: path, perm: perm}
+}
+
+// String returns the raw path without creating the directory. Satisfies fmt.Stringer.
+func (d *Dir) String() string {
+	return d.path
+}
+
+// Path creates the directory on first call (via sync.Once) and returns the path.
+func (d *Dir) Path() (string, error) {
+	d.once.Do(func() {
+		if d.path == "" {
+			return
+		}
+		d.err = os.MkdirAll(d.path, d.perm)
+		if d.err != nil {
+			d.err = fmt.Errorf("creating directory %q: %w", d.path, d.err)
+		}
+	})
+	return d.path, d.err
+}
+
+// MustPath calls Path() and calls logFatal on error.
+func (d *Dir) MustPath() string {
+	path, err := d.Path()
+	if err != nil {
+		logFatal("creating directory:", err)
+	}
+	return path
+}
+
+// GoString implements fmt.GoStringer so that %#v (used by pretty.Sprintf)
+// prints the path string instead of the internal struct fields.
+func (d Dir) GoString() string { //nolint:govet
+	return fmt.Sprintf("%q", d.path)
+}
+
+// MarshalText returns the raw path bytes. No side effects.
+func (d *Dir) MarshalText() ([]byte, error) {
+	return []byte(d.path), nil
+}
+
+// UnmarshalText sets the path from bytes. No side effects.
+func (d *Dir) UnmarshalText(text []byte) error {
+	d.path = string(text)
+	if d.perm == 0 {
+		d.perm = os.ModePerm
+	}
+	return nil
+}

conf/dir_test.go

@@ -0,0 +1,127 @@
+package conf_test
+
+import (
+	"os"
+
+	"github.com/navidrome/navidrome/conf"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Dir", func() {
+	Describe("NewDir", func() {
+		It("creates a Dir with the given path without side effects", func() {
+			d := conf.NewDir("/some/path")
+			Expect(d.String()).To(Equal("/some/path"))
+		})
+	})
+
+	Describe("String", func() {
+		It("returns the raw path without creating the directory", func() {
+			d := conf.NewDir("/nonexistent/path/that/should/not/be/created")
+			Expect(d.String()).To(Equal("/nonexistent/path/that/should/not/be/created"))
+		})
+	})
+
+	Describe("Path", func() {
+		It("creates the directory and returns the path on first call", func() {
+			dir := GinkgoT().TempDir()
+			target := dir + "/subdir/nested"
+			d := conf.NewDir(target)
+
+			path, err := d.Path()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(path).To(Equal(target))
+			Expect(target).To(BeADirectory())
+		})
+
+		It("returns the same result on subsequent calls (sync.Once)", func() {
+			dir := GinkgoT().TempDir()
+			target := dir + "/once"
+			d := conf.NewDir(target)
+
+			path1, err1 := d.Path()
+			path2, err2 := d.Path()
+			Expect(err1).ToNot(HaveOccurred())
+			Expect(err2).ToNot(HaveOccurred())
+			Expect(path1).To(Equal(path2))
+		})
+
+		It("returns an error when directory cannot be created", func() {
+			f := GinkgoT().TempDir()
+			blocker := f + "/blocker"
+			By("creating a file that blocks directory creation")
+			Expect(os.WriteFile(blocker, []byte("x"), 0600)).To(Succeed())
+			invalid := blocker + "/subdir"
+
+			d := conf.NewDir(invalid)
+			_, pathErr := d.Path()
+			Expect(pathErr).To(HaveOccurred())
+		})
+
+		It("returns empty path and no error for empty path", func() {
+			d := conf.NewDir("")
+			path, err := d.Path()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(path).To(BeEmpty())
+		})
+	})
+
+	Describe("MustPath", func() {
+		It("returns the path when directory is created successfully", func() {
+			dir := GinkgoT().TempDir()
+			target := dir + "/mustpath"
+			d := conf.NewDir(target)
+
+			path := d.MustPath()
+			Expect(path).To(Equal(target))
+			Expect(target).To(BeADirectory())
+		})
+
+		It("calls logFatal on error", func() {
+			var fatalMsg []any
+			restore := conf.SetLogFatal(func(args ...any) {
+				fatalMsg = args
+				panic("logFatal called")
+			})
+			DeferCleanup(restore)
+
+			f := GinkgoT().TempDir() + "/blocker"
+			Expect(os.WriteFile(f, []byte("x"), 0600)).To(Succeed())
+			invalid := f + "/subdir"
+
+			d := conf.NewDir(invalid)
+			Expect(func() { d.MustPath() }).To(Panic())
+			Expect(fatalMsg).ToNot(BeEmpty())
+		})
+	})
+
+	Describe("MarshalText", func() {
+		It("returns the raw path bytes without side effects", func() {
+			d := conf.NewDir("/marshal/path")
+			b, err := d.MarshalText()
+			Expect(err).ToNot(HaveOccurred())
+			Expect(string(b)).To(Equal("/marshal/path"))
+		})
+	})
+
+	Describe("UnmarshalText", func() {
+		It("sets the path from bytes without side effects", func() {
+			d := conf.NewDir("")
+			err := d.UnmarshalText([]byte("/unmarshal/path"))
+			Expect(err).ToNot(HaveOccurred())
+			Expect(d.String()).To(Equal("/unmarshal/path"))
+		})
+
+		It("allows round-trip marshal/unmarshal", func() {
+			d1 := conf.NewDir("/round/trip")
+			b, err := d1.MarshalText()
+			Expect(err).ToNot(HaveOccurred())
+
+			var d2 conf.Dir
+			err = d2.UnmarshalText(b)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(d2.String()).To(Equal(d1.String()))
+		})
+	})
+})

core/artwork/benchmark_e2e_test.go

@@ -52,7 +52,7 @@ func setupE2EBenchmark(b *testing.B, cacheSize string) (Artwork, model.ArtworkID
 
 	// Configure cache
 	conf.Server.ImageCacheSize = cacheSize
-	conf.Server.CacheFolder = tmpDir
+	conf.Server.CacheFolder = conf.NewDir(tmpDir)
 	conf.Server.CoverArtQuality = 75
 	conf.Server.CoverArtPriority = "cover.*"
 

core/artwork/e2e/suite_test.go

@@ -63,7 +63,7 @@ func setupHarness() {
 	// Reuse the suite-level DB path so the singleton connection keeps working
 	// across specs (see suiteDBTempDir comment).
 	conf.Server.DbPath = filepath.Join(suiteDBTempDir, "artwork-e2e.db") + "?_journal_mode=WAL"
-	conf.Server.DataFolder = tempDir
+	conf.Server.DataFolder = conf.NewDir(tempDir)
 	conf.Server.MusicFolder = fakeLibPath
 	conf.Server.DevExternalScanner = false
 	conf.Server.ImageCacheSize = "0" // disabled cache → reader runs on every call

core/artwork/reader_artist_test.go

@@ -452,7 +452,7 @@ var _ = Describe("artistArtworkReader", func() {
 		BeforeEach(func() {
 			DeferCleanup(configtest.SetupConfig())
 			tempDir = GinkgoT().TempDir()
-			conf.Server.DataFolder = tempDir
+			conf.Server.DataFolder = conf.NewDir(tempDir)
 
 			// Create the artwork/artist directory
 			Expect(os.MkdirAll(filepath.Join(tempDir, "artwork", "artist"), 0755)).To(Succeed())

core/artwork/reader_radio_test.go

@@ -21,7 +21,7 @@ var _ = Describe("radioArtworkReader", func() {
 	BeforeEach(func() {
 		DeferCleanup(configtest.SetupConfig())
 		tempDir = GinkgoT().TempDir()
-		conf.Server.DataFolder = tempDir
+		conf.Server.DataFolder = conf.NewDir(tempDir)
 
 		Expect(os.MkdirAll(filepath.Join(tempDir, "artwork", "radio"), 0755)).To(Succeed())
 

core/image_upload_test.go

@@ -21,7 +21,7 @@ var _ = Describe("ImageUploadService", func() {
 	BeforeEach(func() {
 		DeferCleanup(configtest.SetupConfig())
 		tmpDir = GinkgoT().TempDir()
-		conf.Server.DataFolder = tmpDir
+		conf.Server.DataFolder = conf.NewDir(tmpDir)
 		svc = core.NewImageUploadService()
 	})
 

core/metrics/insights.go

@@ -165,7 +165,7 @@ var staticData = sync.OnceValue(func() insights.Data {
 	data.OS.Containerized = consts.InContainer
 
 	// Install info
-	packageFilename := filepath.Join(conf.Server.DataFolder, ".package")
+	packageFilename := filepath.Join(conf.Server.DataFolder.String(), ".package")
 	packageFileData, err := os.ReadFile(packageFilename)
 	if err == nil {
 		data.OS.Package = string(packageFileData)
@@ -179,12 +179,12 @@ var staticData = sync.OnceValue(func() insights.Data {
 
 	// FS info
 	data.FS.Music = getFSInfo(conf.Server.MusicFolder)
-	data.FS.Data = getFSInfo(conf.Server.DataFolder)
-	if conf.Server.CacheFolder != "" {
-		data.FS.Cache = getFSInfo(conf.Server.CacheFolder)
+	data.FS.Data = getFSInfo(conf.Server.DataFolder.String())
+	if conf.Server.CacheFolder.String() != "" {
+		data.FS.Cache = getFSInfo(conf.Server.CacheFolder.String())
 	}
-	if conf.Server.Backup.Path != "" {
-		data.FS.Backup = getFSInfo(conf.Server.Backup.Path)
+	if conf.Server.Backup.Path.String() != "" {
+		data.FS.Backup = getFSInfo(conf.Server.Backup.Path.String())
 	}
 
 	// Config info

core/playlists/playlists_test.go

@@ -307,7 +307,7 @@ var _ = Describe("Playlists", func() {
 		BeforeEach(func() {
 			DeferCleanup(configtest.SetupConfig())
 			tmpDir = GinkgoT().TempDir()
-			conf.Server.DataFolder = tmpDir
+			conf.Server.DataFolder = conf.NewDir(tmpDir)
 
 			mockPlsRepo.Data = map[string]*model.Playlist{
 				"pls-1":     {ID: "pls-1", Name: "My Playlist", OwnerID: "user-1"},
@@ -371,7 +371,7 @@ var _ = Describe("Playlists", func() {
 		BeforeEach(func() {
 			DeferCleanup(configtest.SetupConfig())
 			tmpDir = GinkgoT().TempDir()
-			conf.Server.DataFolder = tmpDir
+			conf.Server.DataFolder = conf.NewDir(tmpDir)
 
 			// Create a real image file on disk
 			imgDir := filepath.Join(tmpDir, "artwork", "playlist")

core/stream/media_streamer_test.go

@@ -23,7 +23,8 @@ var _ = Describe("MediaStreamer", func() {
 
 	BeforeEach(func() {
 		DeferCleanup(configtest.SetupConfig())
-		conf.Server.CacheFolder, _ = os.MkdirTemp("", "file_caches")
+		cacheDir, _ := os.MkdirTemp("", "file_caches")
+		conf.Server.CacheFolder = conf.NewDir(cacheDir)
 		conf.Server.TranscodingCacheSize = "100MB"
 		ds = &tests.MockDataStore{MockedTranscoding: &tests.MockTranscodingRepo{}}
 		ds.MediaFile(ctx).(*tests.MockMediaFileRepo).SetData(model.MediaFiles{
@@ -34,7 +35,7 @@ var _ = Describe("MediaStreamer", func() {
 		streamer = stream.NewMediaStreamer(ds, ffmpeg, testCache)
 	})
 	AfterEach(func() {
-		_ = os.RemoveAll(conf.Server.CacheFolder)
+		_ = os.RemoveAll(conf.Server.CacheFolder.String())
 	})
 
 	Context("NewStream", func() {

db/backup.go

@@ -27,7 +27,7 @@ const backupSuffixLayout = "2006.01.02_15.04.05"
 
 func backupPath(t time.Time) string {
 	return filepath.Join(
-		conf.Server.Backup.Path,
+		conf.Server.Backup.Path.MustPath(),
 		fmt.Sprintf("%s_%s.db", backupPrefix, t.Format(backupSuffixLayout)),
 	)
 }
@@ -117,7 +117,11 @@ func Restore(ctx context.Context, path string) error {
 }
 
 func Prune(ctx context.Context) (int, error) {
-	files, err := os.ReadDir(conf.Server.Backup.Path)
+	backupDir, err := conf.Server.Backup.Path.Path()
+	if err != nil {
+		return 0, fmt.Errorf("backup directory not available: %w", err)
+	}
+	files, err := os.ReadDir(backupDir)
 	if err != nil {
 		return 0, fmt.Errorf("unable to read database backup entries: %w", err)
 	}

db/backup_test.go

@@ -60,7 +60,7 @@ var _ = Describe("database backups", func() {
 
 			tempFolder, err := os.MkdirTemp("", "navidrome_backup")
 			Expect(err).ToNot(HaveOccurred())
-			conf.Server.Backup.Path = tempFolder
+			conf.Server.Backup.Path = conf.NewDir(tempFolder)
 
 			DeferCleanup(func() {
 				_ = os.RemoveAll(tempFolder)
@@ -118,7 +118,7 @@ var _ = Describe("database backups", func() {
 		BeforeEach(func() {
 			tempFolder, err := os.MkdirTemp("", "navidrome_backup")
 			Expect(err).ToNot(HaveOccurred())
-			conf.Server.Backup.Path = tempFolder
+			conf.Server.Backup.Path = conf.NewDir(tempFolder)
 
 			DeferCleanup(func() {
 				_ = os.RemoveAll(tempFolder)

db/db.go

@@ -38,6 +38,8 @@ func Db() *sql.DB {
 		if Path == ":memory:" {
 			Path = "file::memory:?cache=shared&_foreign_keys=on"
 			conf.Server.DbPath = Path
+		} else {
+			conf.Server.DataFolder.MustPath()
 		}
 		log.Debug("Opening DataBase", "dbPath", Path, "driver", Driver)
 		db, err := sql.Open(Driver, Path)

go.mod

@@ -25,6 +25,7 @@ require (
 	github.com/go-chi/httprate v0.15.0
 	github.com/go-chi/jwtauth/v5 v5.4.0
 	github.com/go-viper/encoding/ini v0.1.1
+	github.com/go-viper/mapstructure/v2 v2.5.0
 	github.com/gohugoio/hashstructure v0.6.0
 	github.com/google/go-pipeline v0.0.0-20230411140531-6cbedfc1d3fc
 	github.com/google/uuid v1.6.0
@@ -84,7 +85,6 @@ require (
 	github.com/fsnotify/fsnotify v1.10.1 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
-	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
 	github.com/gobwas/glob v0.2.3 // indirect
 	github.com/goccy/go-json v0.10.6 // indirect
 	github.com/goccy/go-yaml v1.19.2 // indirect

model/artist_test.go

@@ -14,7 +14,7 @@ var _ = Describe("Artist", func() {
 	Describe("UploadedImagePath", func() {
 		BeforeEach(func() {
 			DeferCleanup(configtest.SetupConfig())
-			conf.Server.DataFolder = "/data"
+			conf.Server.DataFolder = conf.NewDir("/data")
 		})
 
 		It("returns empty string when no image uploaded", func() {

model/image.go

@@ -13,5 +13,5 @@ func UploadedImagePath(entityType, filename string) string {
 	if filename == "" {
 		return ""
 	}
-	return filepath.Join(conf.Server.DataFolder, consts.ArtworkFolder, entityType, filename)
+	return filepath.Join(conf.Server.DataFolder.String(), consts.ArtworkFolder, entityType, filename)
 }

model/radio_test.go

@@ -26,7 +26,7 @@ var _ = Describe("Radio", func() {
 	Describe("UploadedImagePath", func() {
 		BeforeEach(func() {
 			DeferCleanup(configtest.SetupConfig())
-			conf.Server.DataFolder = "/data"
+			conf.Server.DataFolder = conf.NewDir("/data")
 		})
 
 		It("returns empty string when no image uploaded", func() {

persistence/artist_repository_test.go

@@ -840,7 +840,7 @@ var _ = Describe("ArtistRepository", func() {
 		BeforeEach(func() {
 			DeferCleanup(configtest.SetupConfig())
 			tmpDir = GinkgoT().TempDir()
-			conf.Server.DataFolder = tmpDir
+			conf.Server.DataFolder = conf.NewDir(tmpDir)
 
 			ctx := request.WithUser(GinkgoT().Context(), adminUser)
 			repo = NewArtistRepository(ctx, GetDBXBuilder()).(*artistRepository)

plugins/host_artwork_test.go

@@ -47,7 +47,7 @@ var _ = Describe("ArtworkService", Ordered, func() {
 		// Setup config
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.Plugins.Enabled = true
-		conf.Server.Plugins.Folder = tmpDir
+		conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
 		conf.Server.Plugins.AutoReload = false
 
 		// Initialize auth (required for token generation)

plugins/host_cache_test.go

@@ -343,7 +343,7 @@ var _ = Describe("CacheService Integration", Ordered, func() {
 		// Setup config
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.Plugins.Enabled = true
-		conf.Server.Plugins.Folder = tmpDir
+		conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
 		conf.Server.Plugins.AutoReload = false
 
 		// Setup mock DataStore with pre-enabled plugin

plugins/host_config_test.go

@@ -57,7 +57,7 @@ func setupTestConfigPlugin(configJSON string) (*Manager, func(context.Context, t
 	// Setup config
 	DeferCleanup(configtest.SetupConfig())
 	conf.Server.Plugins.Enabled = true
-	conf.Server.Plugins.Folder = tmpDir
+	conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
 	conf.Server.Plugins.AutoReload = false
 
 	// Setup mock DataStore

plugins/host_kvstore.go

@@ -54,7 +54,7 @@ func newKVStoreService(ctx context.Context, pluginName string, perm *KVStorePerm
 	}
 
 	// Create plugin data directory
-	dataDir := filepath.Join(conf.Server.DataFolder, "plugins", pluginName)
+	dataDir := filepath.Join(conf.Server.DataFolder.String(), "plugins", pluginName)
 	if err := os.MkdirAll(dataDir, 0700); err != nil {
 		return nil, fmt.Errorf("creating plugin data directory: %w", err)
 	}

plugins/host_kvstore_test.go

@@ -34,7 +34,7 @@ var _ = Describe("KVStoreService", func() {
 		Expect(err).ToNot(HaveOccurred())
 
 		DeferCleanup(configtest.SetupConfig())
-		conf.Server.DataFolder = tmpDir
+		conf.Server.DataFolder = conf.NewDir(tmpDir)
 
 		// Create service with 1KB limit for testing
 		maxSize := "1KB"
@@ -705,9 +705,9 @@ var _ = Describe("KVStoreService Integration", Ordered, func() {
 		// Setup config
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.Plugins.Enabled = true
-		conf.Server.Plugins.Folder = tmpDir
+		conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
 		conf.Server.Plugins.AutoReload = false
-		conf.Server.DataFolder = tmpDir
+		conf.Server.DataFolder = conf.NewDir(tmpDir)
 
 		// Setup mock DataStore with pre-enabled plugin
 		mockPluginRepo := tests.CreateMockPluginRepo()

plugins/host_library_test.go

@@ -263,7 +263,7 @@ var _ = Describe("LibraryService", Ordered, func() {
 			// the service registration and configuration without full plugin execution
 			DeferCleanup(configtest.SetupConfig())
 			conf.Server.Plugins.Enabled = true
-			conf.Server.Plugins.Folder = tmpDir
+			conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
 
 			// Create mock &tests.MockLibraryRepo{}
 			mockLibRepo := &tests.MockLibraryRepo{}
@@ -357,7 +357,7 @@ var _ = Describe("LibraryService Integration", Ordered, func() {
 		// Setup config
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.Plugins.Enabled = true
-		conf.Server.Plugins.Folder = tmpDir
+		conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
 		conf.Server.Plugins.AutoReload = false
 
 		// Setup mock DataStore with pre-enabled plugin and library

plugins/host_scheduler_test.go

@@ -51,7 +51,7 @@ var _ = Describe("SchedulerService", Ordered, func() {
 		// Setup config
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.Plugins.Enabled = true
-		conf.Server.Plugins.Folder = tmpDir
+		conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
 		conf.Server.Plugins.AutoReload = false
 
 		// Create mock scheduler and timer registry

plugins/host_subsonicapi_test.go

@@ -44,7 +44,7 @@ var _ = Describe("SubsonicAPI Host Function", Ordered, func() {
 		// Setup config
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.Plugins.Enabled = true
-		conf.Server.Plugins.Folder = tmpDir
+		conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
 		conf.Server.Plugins.AutoReload = false
 
 		// Setup mock router and data store

plugins/host_taskqueue.go

@@ -82,7 +82,7 @@ type taskQueueServiceImpl struct {
 
 // newTaskQueueService creates a new taskQueueServiceImpl with its own SQLite database.
 func newTaskQueueService(pluginName string, manager *Manager, maxConcurrency int32) (*taskQueueServiceImpl, error) {
-	dataDir := filepath.Join(conf.Server.DataFolder, "plugins", pluginName)
+	dataDir := filepath.Join(conf.Server.DataFolder.String(), "plugins", pluginName)
 	if err := os.MkdirAll(dataDir, 0700); err != nil {
 		return nil, fmt.Errorf("creating plugin data directory: %w", err)
 	}

plugins/host_taskqueue_test.go

@@ -40,7 +40,7 @@ var _ = Describe("TaskQueueService", func() {
 		Expect(err).ToNot(HaveOccurred())
 
 		DeferCleanup(configtest.SetupConfig())
-		conf.Server.DataFolder = tmpDir
+		conf.Server.DataFolder = conf.NewDir(tmpDir)
 
 		// Create a mock manager with context
 		managerCtx, cancel := context.WithCancel(ctx)
@@ -853,10 +853,10 @@ var _ = Describe("TaskQueueService Integration", Ordered, func() {
 		// Setup config
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.Plugins.Enabled = true
-		conf.Server.Plugins.Folder = tmpDir
+		conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
 		conf.Server.Plugins.AutoReload = false
-		conf.Server.CacheFolder = filepath.Join(tmpDir, "cache")
-		conf.Server.DataFolder = tmpDir
+		conf.Server.CacheFolder = conf.NewDir(filepath.Join(tmpDir, "cache"))
+		conf.Server.DataFolder = conf.NewDir(tmpDir)
 
 		// Setup mock DataStore with pre-enabled plugin
 		mockPluginRepo := tests.CreateMockPluginRepo()

plugins/host_users_test.go

@@ -484,7 +484,7 @@ func createTestUsers(mockUserRepo *tests.MockedUserRepo) {
 // setupTestUsersConfig sets up common plugin configuration
 func setupTestUsersConfig(tmpDir string) {
 	conf.Server.Plugins.Enabled = true
-	conf.Server.Plugins.Folder = tmpDir
+	conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
 	conf.Server.Plugins.AutoReload = false
 }
 

plugins/host_websocket_test.go

@@ -51,7 +51,7 @@ var _ = Describe("WebSocketService", Ordered, func() {
 		// Setup config
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.Plugins.Enabled = true
-		conf.Server.Plugins.Folder = tmpDir
+		conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
 		conf.Server.Plugins.AutoReload = false
 
 		// Setup mock DataStore with pre-enabled plugin

plugins/manager.go

@@ -5,7 +5,6 @@ import (
 	"encoding/json"
 	"fmt"
 	"net/http"
-	"os"
 	"path/filepath"
 	"runtime"
 	"sync"
@@ -124,7 +123,7 @@ func (m *Manager) Start(ctx context.Context) error {
 	m.ctx, m.cancel = context.WithCancel(ctx)
 
 	// Initialize wazero compilation cache for better performance
-	cacheDir := filepath.Join(conf.Server.CacheFolder, "plugins")
+	cacheDir := filepath.Join(conf.Server.CacheFolder.MustPath(), "plugins")
 	purgeCacheBySize(ctx, cacheDir, conf.Server.Plugins.CacheSize)
 
 	var err error
@@ -134,17 +133,12 @@ func (m *Manager) Start(ctx context.Context) error {
 		return fmt.Errorf("creating wazero compilation cache: %w", err)
 	}
 
-	folder := conf.Server.Plugins.Folder
-	if folder == "" {
+	if conf.Server.Plugins.Folder.String() == "" {
 		log.Debug(ctx, "No plugins folder configured")
 		return nil
 	}
 
-	// Create plugins folder if it doesn't exist
-	if err := os.MkdirAll(folder, 0755); err != nil {
-		log.Error(ctx, "Failed to create plugins folder", "folder", folder, err)
-		return fmt.Errorf("creating plugins folder: %w", err)
-	}
+	folder := conf.Server.Plugins.Folder.MustPath()
 
 	log.Info(ctx, "Starting plugin manager", "folder", folder)
 
@@ -431,7 +425,7 @@ func (m *Manager) UpdatePluginLibraries(ctx context.Context, id, librariesJSON s
 // This synchronizes the database with the filesystem, discovering new plugins,
 // updating changed ones, and removing deleted ones.
 func (m *Manager) RescanPlugins(ctx context.Context) error {
-	folder := conf.Server.Plugins.Folder
+	folder := conf.Server.Plugins.Folder.String()
 	if folder == "" {
 		return fmt.Errorf("plugins folder not configured")
 	}

plugins/manager_watcher.go

@@ -19,7 +19,7 @@ const debounceDuration = 2 * time.Second
 // startWatcher starts the file watcher for the plugins folder.
 // It watches for CREATE, WRITE, and REMOVE events on .wasm files.
 func (m *Manager) startWatcher() error {
-	folder := conf.Server.Plugins.Folder
+	folder := conf.Server.Plugins.Folder.String()
 	if folder == "" {
 		return nil
 	}
@@ -146,7 +146,7 @@ func (m *Manager) processPluginEvent(pluginName string) {
 	delete(m.debounceTimers, pluginName)
 	m.debounceMu.Unlock()
 
-	folder := conf.Server.Plugins.Folder
+	folder := conf.Server.Plugins.Folder.String()
 	ndpPath := filepath.Join(folder, pluginName+PackageExtension)
 
 	action := determinePluginAction(ndpPath)

plugins/plugins_suite_test.go

@@ -48,7 +48,7 @@ func TestPlugins(t *testing.T) {
 
 	// Set CacheFolder globally so all tests (including those using
 	// configtest.SetupConfig) inherit it without needing to set it manually.
-	conf.Server.CacheFolder = sharedCacheDir
+	conf.Server.CacheFolder = conf.NewDir(sharedCacheDir)
 
 	log.SetLevel(log.LevelFatal)
 	RegisterFailHandler(Fail)
@@ -126,7 +126,7 @@ func createTestManagerWithPluginsAndMetrics(pluginConfig map[string]map[string]s
 	// Setup config
 	DeferCleanup(configtest.SetupConfig())
 	conf.Server.Plugins.Enabled = true
-	conf.Server.Plugins.Folder = tmpDir
+	conf.Server.Plugins.Folder = conf.NewDir(tmpDir)
 	conf.Server.Plugins.AutoReload = false
 
 	// Setup mock DataStore with pre-enabled plugins

resources/embed.go

@@ -16,6 +16,6 @@ var embedFS embed.FS
 func FS() fs.FS {
 	return merge.FS{
 		Base:    embedFS,
-		Overlay: os.DirFS(path.Join(conf.Server.DataFolder, "resources")),
+		Overlay: os.DirFS(path.Join(conf.Server.DataFolder.String(), "resources")),
 	}
 }

scanner/external.go

@@ -45,8 +45,8 @@ func (s *scannerExternal) scan(ctx context.Context, fullScan bool, targets []mod
 		"scan",
 		"--nobanner", "--subprocess",
 		"--configfile", conf.Server.ConfigFile,
-		"--datafolder", conf.Server.DataFolder,
-		"--cachefolder", conf.Server.CacheFolder,
+		"--datafolder", conf.Server.DataFolder.String(),
+		"--cachefolder", conf.Server.CacheFolder.String(),
 	}
 
 	// Add targets if provided

server/nativeapi/config.go

@@ -97,7 +97,7 @@ func getConfig(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 
 	// Marshal the actual configuration struct to preserve original field names
-	configBytes, err := json.Marshal(*conf.Server)
+	configBytes, err := json.Marshal(conf.Server)
 	if err != nil {
 		log.Error(ctx, "Error marshaling config", err)
 		http.Error(w, "Internal server error", http.StatusInternalServerError)

utils/cache/benchmark_test.go

@@ -28,7 +28,7 @@ func setupBenchCache(b *testing.B, cacheSize string, getReader ReadFunc) (*fileC
 		b.Fatal(err)
 	}
 	b.Cleanup(configtest.SetupConfig())
-	conf.Server.CacheFolder = tmpDir
+	conf.Server.CacheFolder = conf.NewDir(tmpDir)
 
 	fc := NewFileCache("bench", cacheSize, "bench", 0, getReader).(*fileCache)
 

utils/cache/file_caches.go

@@ -262,7 +262,7 @@ func newFSCache(name, cacheSize, cacheFolder string, maxItems int) (fscache.Cach
 
 	lru := NewFileHaunter(name, maxItems, size, consts.DefaultCacheCleanUpInterval)
 	h := fscache.NewLRUHaunterStrategy(lru)
-	cacheFolder = filepath.Join(conf.Server.CacheFolder, cacheFolder)
+	cacheFolder = filepath.Join(conf.Server.CacheFolder.MustPath(), cacheFolder)
 
 	var fs *spreadFS
 	log.Info(fmt.Sprintf("Creating %s cache", name), "path", cacheFolder, "maxSize", humanize.Bytes(size))

utils/cache/file_caches_test.go

@@ -28,14 +28,14 @@ var _ = Describe("File Caches", func() {
 			configtest.SetupConfig()
 			_ = os.RemoveAll(tmpDir)
 		})
-		conf.Server.CacheFolder = tmpDir
+		conf.Server.CacheFolder = conf.NewDir(tmpDir)
 	})
 
 	Describe("NewFileCache", func() {
 		It("creates the cache folder", func() {
 			Expect(callNewFileCache("test", "1k", "test", 0, nil)).ToNot(BeNil())
 
-			_, err := os.Stat(filepath.Join(conf.Server.CacheFolder, "test"))
+			_, err := os.Stat(filepath.Join(conf.Server.CacheFolder.String(), "test"))
 			Expect(os.IsNotExist(err)).To(BeFalse())
 		})