Keep a non-root user's database in the XDG state directory (closes #171)

Without SFDUPES_DATABASE, a user other than root now uses
sfdupes/db.sqlite in the XDG state directory (~/.local/state by
default) instead of failing on /var/lib/sfdupes. scan creates the
missing directories there with mode 0700, as the XDG Base Directory
specification asks. An XDG_STATE_HOME that is not an absolute path is
a fatal error for every subcommand. Root keeps
/var/lib/sfdupes/db.sqlite. sfdupes --help and README say where the
database is. Adds github.com/adrg/xdg, the decided XDG library.

Model: opus-5-5

internal/sfdupes/cli.go

@@ -122,6 +122,14 @@ func run(args []string, stdout, stderr io.Writer) int {
 	}
 }
 
+// databaseHelp says in sfdupes --help where the database is.
+const databaseHelp = `The database is the file SFDUPES_DATABASE names.
+When that is unset or empty, root uses /var/lib/sfdupes/db.sqlite. Any
+other user uses sfdupes/db.sqlite in the XDG state directory:
+$XDG_STATE_HOME, or ~/.local/state when that is unset or empty
+(~/Library/Application Support on macOS). An XDG_STATE_HOME that is
+not an absolute path is an error.`
+
 // newRootCommand builds the command tree. Everything on stdout is
 // machine-readable data, the version line included; all human-facing
 // output (help, usage, errors) goes to stderr.
@@ -140,9 +148,12 @@ func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
 		return nil
 	})
 
+	short := "Find candidate duplicate files by size and head/tail/content SHA-256"
+
 	root := &cobra.Command{
 		Use:   "sfdupes",
-		Short: "Find candidate duplicate files by size and head/tail/content SHA-256",
+		Short: short,
+		Long:  short + ".\n\n" + databaseHelp,
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if showVersion {

internal/sfdupes/cli_test.go

@@ -15,6 +15,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/adrg/xdg"
 	"golang.org/x/sys/unix"
 )
 
@@ -553,13 +554,17 @@ func TestRunNamesDefaultDatabase(t *testing.T) {
 	// line.
 	t.Setenv(databaseEnv, "")
 
-	// Whether scan calls the database new depends on that machine too.
-	scanWant := "scan: database " + defaultDatabasePath + " (default)\n"
+	dbPath, err := defaultDatabasePath(os.Geteuid())
+	if err != nil {
+		t.Fatal(err)
+	}
 
-	_, err := os.Stat(defaultDatabasePath)
+	// Whether scan calls the database new depends on that machine too.
+	scanWant := "scan: database " + dbPath + " (default)\n"
+
+	_, err = os.Stat(dbPath)
 	if errors.Is(err, fs.ErrNotExist) {
-		scanWant = "scan: new database " + defaultDatabasePath +
-			" (default)\n"
+		scanWant = "scan: new database " + dbPath + " (default)\n"
 	}
 
 	missing := filepath.Join(t.TempDir(), "nope")
@@ -579,21 +584,21 @@ func TestRunNamesDefaultDatabase(t *testing.T) {
 			run: func() error {
 				return runReport(cancelledContext(t), io.Discard)
 			},
-			want: "report: database " + defaultDatabasePath + " (default)\n" +
+			want: "report: database " + dbPath + " (default)\n" +
 				reportOpenLine + "\n" + reportOpenLine + "\n",
 		},
 		cmdTrees: {
 			run: func() error {
 				return runTrees(cancelledContext(t), io.Discard)
 			},
-			want: "trees: database " + defaultDatabasePath + " (default)\n" +
+			want: "trees: database " + dbPath + " (default)\n" +
 				treesOpenLine + "\n" + treesOpenLine + "\n",
 		},
 		cmdInfo: {
 			run: func() error {
 				return runInfo(cancelledContext(t), io.Discard)
 			},
-			want: "info: database " + defaultDatabasePath + " (default)\n" +
+			want: "info: database " + dbPath + " (default)\n" +
 				infoOpenLine + "\n" + infoOpenLine + "\n",
 		},
 	}
@@ -712,6 +717,22 @@ func TestRunHelp(t *testing.T) {
 			t.Errorf("run(%v) stdout = %q, want nothing (data only)",
 				args, got)
 		}
+
+		if args[0] == cmdScan {
+			continue
+		}
+
+		// README §Location: sfdupes --help says where the database is,
+		// and that XDG_STATE_HOME must be an absolute path.
+		for _, want := range []string{
+			databaseEnv, rootDatabasePath, stateHomeEnv, "~/.local/state",
+			"not an absolute path is an error",
+		} {
+			if !strings.Contains(stderr.String(), want) {
+				t.Errorf("run(%v) stderr = %q, want it to name %q",
+					args, stderr.String(), want)
+			}
+		}
 	}
 
 	// The scan help lists --exclude with its argument.
@@ -1536,6 +1557,75 @@ func TestRunDatabasePathUsedAsGiven(t *testing.T) {
 	})
 }
 
+func TestRunNonRootUsesStateDirectory(t *testing.T) {
+	// README §Location: without SFDUPES_DATABASE, a user other than
+	// root keeps the database in the XDG state directory. scan creates
+	// the missing directories with mode 0700, and report and trees read
+	// the same file.
+	if os.Geteuid() == 0 {
+		t.Skip("root uses " + rootDatabasePath)
+	}
+
+	t.Cleanup(xdg.Reload)
+
+	state := filepath.Join(t.TempDir(), "state")
+	t.Setenv(stateHomeEnv, state)
+	t.Setenv(databaseEnv, "")
+	xdg.Reload()
+
+	assertRunsUseDatabase(t, filepath.Join(state, "sfdupes"), "db.sqlite")
+
+	for _, dir := range []string{state, filepath.Join(state, "sfdupes")} {
+		fi, err := os.Stat(dir)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		if got := fi.Mode().Perm(); got != stateDirPerm {
+			t.Errorf("%s mode = %#o, want %#o", dir, got, stateDirPerm)
+		}
+	}
+}
+
+func TestRunRelativeStateHomeFails(t *testing.T) {
+	// README §Location: without SFDUPES_DATABASE, a user other than
+	// root whose XDG_STATE_HOME is not an absolute path gets an error
+	// naming it from every subcommand, which exits 1 before it does
+	// anything else.
+	if os.Geteuid() == 0 {
+		t.Skip("root does not use " + stateHomeEnv)
+	}
+
+	t.Setenv(stateHomeEnv, "relative/state")
+	t.Setenv(databaseEnv, "")
+
+	want := "sfdupes: " + stateHomeEnv +
+		" must be an absolute path, got \"relative/state\"\n"
+
+	// A scan that got past the check would stop at this missing
+	// operand, before it creates anything.
+	missing := filepath.Join(t.TempDir(), "missing")
+
+	for _, args := range [][]string{
+		{cmdScan, missing}, {cmdReport}, {cmdTrees}, {cmdInfo},
+	} {
+		var stdout, stderr bytes.Buffer
+
+		code := run(args, &stdout, &stderr)
+		if code != exitFatal || stderr.String() != want {
+			t.Errorf("run(%v) = %d with stderr %q, want %d and %q",
+				args, code, stderr.String(), exitFatal, want)
+		}
+	}
+
+	// dwim scans /, so runDwim gets the missing operand instead.
+	err := runDwim(t.Context(), missing, io.Discard)
+	if !errors.Is(err, errStateHomeNotAbsolute) {
+		t.Errorf("runDwim: error = %v, want %v", err,
+			errStateHomeNotAbsolute)
+	}
+}
+
 // holdScanLock takes the lock on the database at path, as a running
 // scan does, and holds it until the test ends. It fails the test when
 // the lock is already held.

internal/sfdupes/db.go

@@ -15,28 +15,40 @@ import (
 	"strings"
 	"time"
 
+	"github.com/adrg/xdg"
 	"golang.org/x/sys/unix"
 	// The pure-Go SQLite driver, registered as "sqlite"; keeps cgo
 	// disabled.
 	_ "modernc.org/sqlite"
 )
 
-// defaultDatabasePath is where the persistent scan database lives when
-// SFDUPES_DATABASE is not set.
-const defaultDatabasePath = "/var/lib/sfdupes/db.sqlite"
+// rootDatabasePath is the database root uses when SFDUPES_DATABASE is
+// not set.
+const rootDatabasePath = "/var/lib/sfdupes/db.sqlite"
 
 // databaseEnv is the environment variable that overrides the database
 // path.
 const databaseEnv = "SFDUPES_DATABASE"
 
+// stateHomeEnv is the environment variable that names the XDG state
+// directory.
+const stateHomeEnv = "XDG_STATE_HOME"
+
 // schemaVersion is the database schema version this build reads and
 // writes, stored in PRAGMA user_version.
 const schemaVersion = 1
 
-// dbDirPerm is the mode for a database parent directory created by
-// scan.
+// dbDirPerm is the mode for a directory scan creates for root's
+// default database or for SFDUPES_DATABASE.
 const dbDirPerm = 0o755
 
+// stateDirPerm is the mode for a directory scan creates for the
+// database at a user's default path in the XDG state directory. It is
+// the mode the XDG Base Directory specification asks for, and it keeps
+// other users from reading the database, which lists every scanned
+// path.
+const stateDirPerm = 0o700
+
 // dbFilePerm is the mode for a database file created by scan, the mode
 // SQLite gives a database file it creates.
 const dbFilePerm = 0o644
@@ -144,15 +156,48 @@ var errScanRunning = errors.New("another scan is running")
 // 32 bytes of a SHA-256.
 var errHashSize = errors.New("hash is not 32 bytes")
 
+// errStateHomeNotAbsolute reports an XDG_STATE_HOME that is set to a
+// path that is not absolute.
+var errStateHomeNotAbsolute = errors.New(
+	stateHomeEnv + " must be an absolute path")
+
+// defaultDatabasePath is the database used when SFDUPES_DATABASE is not
+// set: rootDatabasePath for root (euid 0), and db.sqlite in the
+// directory sfdupes under the XDG state directory for any other user.
+// xdg reads XDG_STATE_HOME and HOME once, when the program starts. For
+// any other user, an XDG_STATE_HOME that is set and not an absolute
+// path is an error, where xdg would use its default instead. The path
+// is joined as text, not cleaned, for the reason absolutePath gives.
+func defaultDatabasePath(euid int) (string, error) {
+	if euid == 0 {
+		return rootDatabasePath, nil
+	}
+
+	stateHome := os.Getenv(stateHomeEnv)
+	if stateHome != "" && !filepath.IsAbs(stateHome) {
+		return "", fmt.Errorf("%w, got %q", errStateHomeNotAbsolute,
+			stateHome)
+	}
+
+	stateDir := strings.TrimSuffix(xdg.StateHome, "/")
+
+	return stateDir + "/sfdupes/db.sqlite", nil
+}
+
 // databasePath resolves the database location: SFDUPES_DATABASE when
-// set and non-empty, the compiled-in default otherwise. It returns the
+// set and non-empty, defaultDatabasePath otherwise. It returns the
 // path, made absolute by absolutePath, and where the path came from,
 // "default" or "from SFDUPES_DATABASE", for the line each subcommand
 // prints first on stderr.
 func databasePath() (string, string, error) {
-	path, source := defaultDatabasePath, "default"
-	if p := os.Getenv(databaseEnv); p != "" {
-		path, source = p, "from "+databaseEnv
+	path, source := os.Getenv(databaseEnv), "from "+databaseEnv
+	if path == "" {
+		def, err := defaultDatabasePath(os.Geteuid())
+		if err != nil {
+			return "", "", err
+		}
+
+		path, source = def, "default"
 	}
 
 	abs, err := absolutePath(path)
@@ -188,15 +233,23 @@ func absolutePath(path string) (string, error) {
 
 // createDatabaseDirectory creates the directory the database at path
 // goes in, and any directory above it, if missing. path is absolute, as
-// databasePath returns it. The directory is path with its last element
-// cut off as text, by filepath.Split. filepath.Dir would clean it,
-// dropping each ".." together with the directory name before it; when
-// that name is a symlink, the cleaned path names another directory than
-// the one the system reaches when it opens path.
+// databasePath returns it. Each directory gets mode dbDirPerm, or
+// stateDirPerm when databasePath uses a user's default path in the XDG
+// state directory: the user is not root and SFDUPES_DATABASE is unset
+// or empty. The directory is path with its last element cut off as
+// text, by filepath.Split. filepath.Dir would clean it, dropping each
+// ".." together with the directory name before it; when that name is a
+// symlink, the cleaned path names another directory than the one the
+// system reaches when it opens path.
 func createDatabaseDirectory(path string) error {
 	dir, _ := filepath.Split(path)
 
-	err := os.MkdirAll(dir, dbDirPerm)
+	perm := os.FileMode(dbDirPerm)
+	if os.Geteuid() != 0 && os.Getenv(databaseEnv) == "" {
+		perm = stateDirPerm
+	}
+
+	err := os.MkdirAll(dir, perm)
 	if err != nil {
 		return fmt.Errorf("create database directory: %w", err)
 	}

internal/sfdupes/db_test.go

@@ -9,10 +9,13 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"runtime"
 	"slices"
 	"strings"
 	"testing"
 	"time"
+
+	"github.com/adrg/xdg"
 )
 
 // testDBPath returns a database path inside a fresh temp dir, with
@@ -56,11 +59,16 @@ func TestDatabasePath(t *testing.T) {
 
 	t.Chdir(dir)
 
+	defaultPath, err := defaultDatabasePath(os.Geteuid())
+	if err != nil {
+		t.Fatal(err)
+	}
+
 	fromEnv := "from " + databaseEnv
 	cases := []struct {
 		env, path, source string
 	}{
-		{"", defaultDatabasePath, "default"},
+		{"", defaultPath, "default"},
 		{"/custom/place.sqlite", "/custom/place.sqlite", fromEnv},
 		{"/custom/link/../place.sqlite", "/custom/link/../place.sqlite",
 			fromEnv},
@@ -89,6 +97,48 @@ func TestDatabasePath(t *testing.T) {
 	}
 }
 
+func TestDefaultDatabasePath(t *testing.T) {
+	// README §Location: root's database is /var/lib/sfdupes/db.sqlite.
+	// Any other user's is db.sqlite in sfdupes under XDG_STATE_HOME, or
+	// under ~/.local/state when XDG_STATE_HOME is unset or empty. For
+	// that user, an XDG_STATE_HOME that is not an absolute path is an
+	// error.
+	if runtime.GOOS != goosLinux {
+		t.Skip("macOS has another default state directory")
+	}
+
+	t.Cleanup(xdg.Reload)
+	t.Setenv("HOME", "/home/someone")
+
+	cases := []struct {
+		euid      int
+		stateHome string
+		want      string
+		wantErr   error
+	}{
+		{0, "", rootDatabasePath, nil},
+		{0, "/elsewhere/state", rootDatabasePath, nil},
+		{0, "relative/state", rootDatabasePath, nil},
+		{1000, "", "/home/someone/.local/state/sfdupes/db.sqlite", nil},
+		{1000, "relative/state", "", errStateHomeNotAbsolute},
+		{1000, "~/state", "", errStateHomeNotAbsolute},
+		{1000, "/elsewhere/state", "/elsewhere/state/sfdupes/db.sqlite", nil},
+		{1000, "/elsewhere/state/", "/elsewhere/state/sfdupes/db.sqlite", nil},
+	}
+
+	for _, tc := range cases {
+		t.Setenv(stateHomeEnv, tc.stateHome)
+		xdg.Reload()
+
+		got, err := defaultDatabasePath(tc.euid)
+		if got != tc.want || !errors.Is(err, tc.wantErr) {
+			t.Errorf("defaultDatabasePath(%d) with %s=%q = %q, %v; want %q, %v",
+				tc.euid, stateHomeEnv, tc.stateHome, got, err, tc.want,
+				tc.wantErr)
+		}
+	}
+}
+
 func TestOpenScanDatabaseCreates(t *testing.T) {
 	t.Parallel()