kept data: the choice at reinstall, the list, the read-only view, the load (09 decision 36); R-690 fixed

An install over an app's kept drive folder (appdata/<app> non-empty) asks the household: "use my kept data" (a load from the newest copy of THIS drive's install, own unit or second-drive mirror, then the template's after_load) or "start fresh" (the folder is renamed into <drive>/kept/<app>/<date>/ with the removed app's unit; nothing deleted). The install API answers 409 kept_data_choice until one is chosen; DeployStack refuses too. New page Megorzott adatok / Kept data (/kept-data): Load / Look / Delete (typed confirmation, the only deletion of kept data). FileBrowser gets a read-only source. The drive-full warning names the kept folders. <drive>/kept is protected and outside every backup leg. R-690: the removed-app restore (R-487) never found a unit on a DATA drive — it asked GetStackComposePath (true for every catalog app) and restored nextcloud with no env. Now isStackDeployed; pinned with a production-shaped provider. Red-proofs: audits/night-2026-09-26/E/redproofs/. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS
2026-09-25 13:32:30 +02:00
parent 5a731b45b9
commit 43e99d160c
44 changed files with 3311 additions and 37 deletions
@@ -0,0 +1,557 @@
+package stacks
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"syscall"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-controller/internal/util"
+)
+
+// ── Kept data (`09` §3 decision 36, operator ruling 2026-09-25 evening) ────────────────────────────
+//
+// WHAT IT REPLACES. „Remove the app, keep my data" left the app's private drive folder
+// (`<drive>/appdata/<app>`) behind, and a later install of the same app ran straight into it (R-657):
+// measured 2026-09-23 as an install loop, and 2026-09-25 as a clean install whose database simply knows
+// nothing of the old files. Nothing listed the folder, nothing opened it, nothing deleted it.
+//
+// THE RULING. A reinstall over kept data asks: "use my kept data" (the database from a backup, with the
+// kept files) or "start fresh" (the kept files MOVE to a dated folder; nothing is deleted). And kept data
+// is never a dead end: the household can see it (read only), load it later, and delete it.
+//
+// FOUR RULES, each a guard with a test:
+//
+//  1. ONLY `<drive>/appdata/<…>` IS "OLD DATA". An app's bind under userdata/ or media/ is the household's
+//     own shared files (a music library, a photo folder) — never moved, never listed here. Pinned by
+//     TestKept_OnlyAppdataBindsAreOldData.
+//  2. "START FRESH" IS A RENAME ON THE SAME DRIVE — never a copy, never across drives. A rename that
+//     fails with EXDEV (or anything else) puts back what it already moved and refuses. Pinned by
+//     TestKept_KeepAsideIsARenameAndRollsBack.
+//  3. THE KEPT FOLDER IS `<drive>/kept/<app>/<date>/` — beside appdata/ and userdata/, inside neither:
+//     no app bind reaches it, FileBrowser and Samba serve only userdata/, and no backup leg reads it (the
+//     Tier-2 and off-site legs read userdata/ and the declared binds of DEPLOYED apps). It is in
+//     ProtectedHDDPaths. The page says it is not backed up.
+//  4. THE BOX NEVER DELETES KEPT DATA BY ITSELF (D3 is open). DeleteKept is reachable only from the
+//     household's typed confirmation, and refuses any path that is not a listed kept item. Pinned by
+//     TestKept_DeleteRefusesAnythingNotListed.
+
+// KeptDirName is the folder at a drive's namespace root that holds the dated kept folders.
+const KeptDirName = "kept"
+
+// keptMarkerFile is written LAST into a dated kept folder: what was moved, from where, and when.
+const keptMarkerFile = ".felhom-kept.json"
+
+// keptUnitDir is where a start-fresh moves the removed app's recovery unit, so the kept files keep the
+// database copy that belongs to them (the next backup of the fresh install would overwrite it in place).
+const keptUnitDir = "unit"
+
+// Kept item kinds.
+const (
+	KeptKindDated    = "dated"    // a start-fresh folder under <drive>/kept/<app>/<date>
+	KeptKindLeftover = "leftover" // <drive>/appdata/<x> that no installed app binds (a plain keep-data remove)
+)
+
+// KeptMarker is the record inside a dated kept folder.
+type KeptMarker struct {
+	App     string   `json:"app"`
+	MovedAt string   `json:"moved_at"`        // RFC3339 UTC
+	Paths   []string `json:"paths"`           // relative to the drive root, as they were (e.g. appdata/nextcloud)
+	Unit    bool     `json:"unit,omitempty"`  // a recovery unit was moved in with them (<kept>/unit)
+	Drive   string   `json:"drive,omitempty"` // the drive root they came from
+}
+
+// KeptItem is one row of the „Megőrzött adatok" list.
+type KeptItem struct {
+	App         string    `json:"app"`          // the catalog app it belongs to ("" = unknown)
+	DisplayName string    `json:"display_name"` // the app's name, else the folder name
+	Path        string    `json:"path"`         // the kept folder (absolute)
+	Drive       string    `json:"drive"`        // the drive root it sits on
+	Kind        string    `json:"kind"`
+	Date        time.Time `json:"date"`
+	SizeBytes   int64     `json:"size_bytes"`
+	// UnitDir is the recovery unit moved in with a dated folder ("" none) — its database copy.
+	UnitDir string `json:"unit_dir,omitempty"`
+	// Marker is the dated folder's record (nil for a leftover).
+	Marker *KeptMarker `json:"marker,omitempty"`
+}
+
+// Errors, born as bundle keys.
+var (
+	ErrKeptNotListed = util.MsgError("err.kept.not_listed")
+	ErrKeptOccupied  = util.MsgError("err.kept.occupied")
+)
+
+// OldAppDataPaths is rule 1 as a pure function: the app's binds under `<hdd>/appdata/` (never appdata
+// itself) that exist and hold at least one entry.
+func OldAppDataPaths(composePath, hddPath string) []string {
+	if hddPath == "" {
+		return nil
+	}
+	appdata := filepath.Join(filepath.Clean(hddPath), "appdata") + string(filepath.Separator)
+	var out []string
+	for _, p := range ParseComposeHDDMounts(composePath, hddPath) {
+		p = filepath.Clean(p)
+		if !strings.HasPrefix(p, appdata) {
+			continue
+		}
+		if dirHasEntries(p) {
+			out = append(out, p)
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+func dirHasEntries(p string) bool {
+	f, err := os.Open(p)
+	if err != nil {
+		return false
+	}
+	defer f.Close()
+	names, _ := f.Readdirnames(1)
+	return len(names) > 0
+}
+
+// OldAppData is OldAppDataPaths for an app about to be installed on hddPath (its catalog definition).
+func (m *Manager) OldAppData(name, hddPath string) []string {
+	st, ok := m.GetStack(name)
+	if !ok || st.ComposePath == "" {
+		return nil
+	}
+	return OldAppDataPaths(st.ComposePath, hddPath)
+}
+
+// KeptDirFor names a new dated kept folder. The date is the box's local day and time, so the household
+// recognises „today" in the name.
+func KeptDirFor(hddPath, app string, now time.Time) string {
+	return filepath.Join(filepath.Clean(hddPath), KeptDirName, app, now.In(getTimezone()).Format("2006-01-02_150405"))
+}
+
+// renameFn is the rename seam (tests inject EXDEV); production is os.Rename.
+var renameFn = os.Rename
+
+// KeepAside is "start fresh": it MOVES each old-data folder (and, when unitDir is on the same drive, the
+// removed app's recovery unit) into a new dated kept folder, keeping each one's path relative to the drive.
+// A failed move puts back everything already moved and returns the error — nothing is copied, nothing is
+// deleted. Returns the kept folder.
+func (m *Manager) KeepAside(name, hddPath string, paths []string, unitDir string, now time.Time) (string, error) {
+	drive := filepath.Clean(hddPath)
+	if len(paths) == 0 {
+		return "", fmt.Errorf("nothing to keep aside for %s", name)
+	}
+	dest := KeptDirFor(drive, name, now)
+	if _, err := os.Stat(dest); err == nil {
+		return "", fmt.Errorf("the kept folder %s already exists", dest)
+	}
+	if err := os.MkdirAll(dest, 0o755); err != nil {
+		return "", fmt.Errorf("creating the kept folder: %w", err)
+	}
+	type moved struct{ from, to string }
+	var done []moved
+	undo := func() {
+		for i := len(done) - 1; i >= 0; i-- {
+			if err := renameFn(done[i].to, done[i].from); err != nil {
+				m.logger.Printf("[ERROR] [stacks] kept %s: putting %s back to %s FAILED: %v", name, done[i].to, done[i].from, err)
+			}
+		}
+		removeEmptyDirs(dest) // os.Remove only: a folder a failed move-back left data in STAYS
+	}
+	marker := KeptMarker{App: name, MovedAt: now.UTC().Format(time.RFC3339), Drive: drive}
+	for _, p := range paths {
+		p = filepath.Clean(p)
+		rel, err := filepath.Rel(drive, p)
+		if err != nil || strings.HasPrefix(rel, "..") || !strings.HasPrefix(rel, "appdata"+string(filepath.Separator)) {
+			undo()
+			return "", fmt.Errorf("refusing to keep aside %s: not under %s/appdata", p, drive)
+		}
+		to := filepath.Join(dest, rel)
+		if err := os.MkdirAll(filepath.Dir(to), 0o755); err != nil {
+			undo()
+			return "", err
+		}
+		if err := renameFn(p, to); err != nil {
+			undo()
+			if errors.Is(err, syscall.EXDEV) {
+				return "", fmt.Errorf("moving %s would cross drives — refused, nothing moved: %w", p, err)
+			}
+			return "", fmt.Errorf("moving %s: %w — nothing moved", p, err)
+		}
+		done = append(done, moved{p, to})
+		marker.Paths = append(marker.Paths, rel)
+		m.logger.Printf("[INFO] [stacks] kept %s: moved %s → %s (start fresh)", name, p, to)
+	}
+	if unitDir != "" {
+		to := filepath.Join(dest, keptUnitDir)
+		if err := renameFn(unitDir, to); err != nil {
+			// The files are kept either way; without the unit a later Load has no database copy, which
+			// the list then says. Not a reason to undo the household's choice.
+			m.logger.Printf("[WARN] [stacks] kept %s: the recovery unit %s could not move in with the files (%v) — the kept folder has no database copy", name, unitDir, err)
+		} else {
+			marker.Unit = true
+			m.logger.Printf("[INFO] [stacks] kept %s: moved the recovery unit %s → %s", name, unitDir, to)
+		}
+	}
+	b, _ := json.MarshalIndent(marker, "", "  ")
+	if err := os.WriteFile(filepath.Join(dest, keptMarkerFile), b, 0o644); err != nil {
+		m.logger.Printf("[WARN] [stacks] kept %s: could not write the marker in %s: %v — listed without it", name, dest, err)
+	}
+	return dest, nil
+}
+
+func readKeptMarker(dir string) *KeptMarker {
+	b, err := os.ReadFile(filepath.Join(dir, keptMarkerFile))
+	if err != nil {
+		return nil
+	}
+	var mk KeptMarker
+	if json.Unmarshal(b, &mk) != nil {
+		return nil
+	}
+	return &mk
+}
+
+// liveDriveBinds is every drive folder an INSTALLED app binds — never kept data.
+func (m *Manager) liveDriveBinds() []string {
+	var out []string
+	for _, st := range m.GetStacks() {
+		if !st.Deployed || st.AppConfig == nil {
+			continue
+		}
+		hdd := strings.TrimSpace(st.AppConfig.Env["HDD_PATH"])
+		if hdd == "" {
+			continue
+		}
+		for _, p := range ParseComposeHDDMounts(st.ComposePath, hdd) {
+			out = append(out, filepath.Clean(p))
+		}
+	}
+	return out
+}
+
+func overlaps(a, b string) bool {
+	sep := string(filepath.Separator)
+	return a == b || strings.HasPrefix(a, b+sep) || strings.HasPrefix(b, a+sep)
+}
+
+// ownerOf names the catalog app whose definition binds drive-relative folder rel (e.g. appdata/paperless
+// → paperless-ngx). A stack named like the folder wins; "" when none declares it.
+func (m *Manager) ownerOf(drive, abs string) (string, string) {
+	var cands []Stack
+	for _, st := range m.GetStacks() {
+		if st.ComposePath == "" {
+			continue
+		}
+		for _, p := range ParseComposeHDDMounts(st.ComposePath, drive) {
+			if filepath.Clean(p) == abs {
+				cands = append(cands, st)
+				break
+			}
+		}
+	}
+	if len(cands) == 0 {
+		return "", ""
+	}
+	pick := cands[0]
+	for _, c := range cands {
+		if c.Name == filepath.Base(abs) {
+			pick = c
+		}
+	}
+	dn := pick.Meta.DisplayName
+	if dn == "" {
+		dn = pick.Name
+	}
+	return pick.Name, dn
+}
+
+// sizeFn is the size seam (production walks the tree).
+var sizeFn = getDirSizeBytes
+
+// ListKept lists every kept item on the given drive roots: the dated folders under <drive>/kept/<app>/,
+// and each <drive>/appdata/<x> that holds something and that no installed app binds. Sorted newest first.
+func (m *Manager) ListKept(drives []string) []KeptItem {
+	live := m.liveDriveBinds()
+	var out []KeptItem
+	seen := map[string]bool{}
+	for _, d := range drives {
+		d = filepath.Clean(d)
+		if d == "" || seen[d] {
+			continue
+		}
+		seen[d] = true
+		apps, _ := os.ReadDir(filepath.Join(d, KeptDirName))
+		for _, a := range apps {
+			if !a.IsDir() {
+				continue
+			}
+			stamps, _ := os.ReadDir(filepath.Join(d, KeptDirName, a.Name()))
+			for _, s := range stamps {
+				if !s.IsDir() {
+					continue
+				}
+				dir := filepath.Join(d, KeptDirName, a.Name(), s.Name())
+				it := KeptItem{App: a.Name(), DisplayName: a.Name(), Path: dir, Drive: d, Kind: KeptKindDated,
+					Marker: readKeptMarker(dir), SizeBytes: sizeFn(dir)}
+				if st, ok := m.GetStack(a.Name()); ok && st.Meta.DisplayName != "" {
+					it.DisplayName = st.Meta.DisplayName
+				}
+				if it.Marker != nil {
+					if t, err := time.Parse(time.RFC3339, it.Marker.MovedAt); err == nil {
+						it.Date = t
+					}
+					if it.Marker.Unit {
+						if _, err := os.Stat(filepath.Join(dir, keptUnitDir)); err == nil {
+							it.UnitDir = filepath.Join(dir, keptUnitDir)
+						}
+					}
+				}
+				if it.Date.IsZero() {
+					if fi, err := os.Stat(dir); err == nil {
+						it.Date = fi.ModTime()
+					}
+				}
+				out = append(out, it)
+			}
+		}
+		ents, _ := os.ReadDir(filepath.Join(d, "appdata"))
+		for _, e := range ents {
+			if !e.IsDir() {
+				continue
+			}
+			abs := filepath.Join(d, "appdata", e.Name())
+			isLive := false
+			for _, l := range live {
+				if overlaps(abs, l) {
+					isLive = true
+					break
+				}
+			}
+			if isLive || !dirHasEntries(abs) {
+				continue
+			}
+			app, dn := m.ownerOf(d, abs)
+			if dn == "" {
+				dn = e.Name()
+			}
+			it := KeptItem{App: app, DisplayName: dn, Path: abs, Drive: d, Kind: KeptKindLeftover, SizeBytes: sizeFn(abs)}
+			if fi, err := os.Stat(abs); err == nil {
+				it.Date = fi.ModTime()
+			}
+			out = append(out, it)
+		}
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if !out[i].Date.Equal(out[j].Date) {
+			return out[i].Date.After(out[j].Date)
+		}
+		return out[i].Path < out[j].Path
+	})
+	return out
+}
+
+// FindKept returns the listed item at exactly path — the only way an action names a kept item.
+func (m *Manager) FindKept(drives []string, path string) (KeptItem, bool) {
+	clean := filepath.Clean(path)
+	for _, it := range m.ListKept(drives) {
+		if it.Path == clean {
+			return it, true
+		}
+	}
+	return KeptItem{}, false
+}
+
+// DeleteKept is the household's Delete, and the ONLY deletion of kept data anywhere in the product
+// (rule 4). It refuses a path that is not a listed kept item — a live app's folder is never listed.
+func (m *Manager) DeleteKept(drives []string, path string) (KeptItem, error) {
+	it, ok := m.FindKept(drives, path)
+	if !ok {
+		m.logger.Printf("[WARN] [stacks] kept: delete REFUSED for %s — not a listed kept item", path)
+		return KeptItem{}, ErrKeptNotListed
+	}
+	if err := os.RemoveAll(it.Path); err != nil {
+		return it, fmt.Errorf("deleting %s: %w", it.Path, err)
+	}
+	m.logger.Printf("[INFO] [stacks] kept: DELETED %s (%s, %d bytes) — the household's typed confirmation", it.Path, it.DisplayName, it.SizeBytes)
+	if it.Kind == KeptKindDated {
+		_ = os.Remove(filepath.Dir(it.Path)) // the per-app folder, only when now empty
+	}
+	return it, nil
+}
+
+// RestoreKeptFiles puts a dated item's files back where they were (a rename, the reverse of KeepAside)
+// before a Load; a leftover item is already in place. It refuses when any destination holds something —
+// that would be two installs' data in one folder. Returns the unit to load from ("" none).
+func (m *Manager) RestoreKeptFiles(it KeptItem) (string, error) {
+	if it.Kind != KeptKindDated {
+		return "", nil
+	}
+	if it.Marker == nil || len(it.Marker.Paths) == 0 {
+		return "", fmt.Errorf("the kept folder %s has no record of where its files came from", it.Path)
+	}
+	for _, rel := range it.Marker.Paths {
+		if dirHasEntries(filepath.Join(it.Drive, rel)) {
+			return "", ErrKeptOccupied
+		}
+	}
+	var done []string
+	for _, rel := range it.Marker.Paths {
+		from, to := filepath.Join(it.Path, rel), filepath.Join(it.Drive, rel)
+		_ = os.Remove(to) // an EMPTY leftover directory only (checked above)
+		if err := os.MkdirAll(filepath.Dir(to), 0o755); err != nil {
+			return "", err
+		}
+		if err := renameFn(from, to); err != nil {
+			for _, r := range done {
+				_ = renameFn(filepath.Join(it.Drive, r), filepath.Join(it.Path, r))
+			}
+			return "", fmt.Errorf("moving %s back: %w — nothing moved", from, err)
+		}
+		done = append(done, rel)
+		m.logger.Printf("[INFO] [stacks] kept %s: moved %s back → %s (load)", it.App, from, to)
+	}
+	return it.UnitDir, nil
+}
+
+// FinishKeptLoad runs after a successful Load of a dated item: the unit it carried becomes the app's own
+// unit again when that place is free (unitHome = backups/primary/<app> on the drive), and the kept folder
+// is removed only when nothing but empty directories and its marker remain — no data is deleted here.
+func (m *Manager) FinishKeptLoad(it KeptItem, unitHome string) {
+	if it.Kind != KeptKindDated {
+		return
+	}
+	if it.UnitDir != "" && unitHome != "" {
+		if _, err := os.Stat(unitHome); os.IsNotExist(err) {
+			if err := os.MkdirAll(filepath.Dir(unitHome), 0o755); err == nil {
+				if err := renameFn(it.UnitDir, unitHome); err == nil {
+					m.logger.Printf("[INFO] [stacks] kept %s: the loaded unit is the app's own again → %s", it.App, unitHome)
+				}
+			}
+		} else {
+			m.logger.Printf("[INFO] [stacks] kept %s: %s already holds a unit — the loaded one stays in %s (listed; the household decides)", it.App, unitHome, it.UnitDir)
+		}
+	}
+	if keptHoldsOnlyEmptyDirs(it.Path) {
+		_ = os.Remove(filepath.Join(it.Path, keptMarkerFile))
+		removeEmptyDirs(it.Path)
+		if _, err := os.Stat(it.Path); os.IsNotExist(err) {
+			_ = os.Remove(filepath.Dir(it.Path))
+			m.logger.Printf("[INFO] [stacks] kept %s: %s is empty after the load — removed from the list", it.App, it.Path)
+		}
+	}
+}
+
+// keptHoldsOnlyEmptyDirs: true when the tree holds no file other than the marker.
+func keptHoldsOnlyEmptyDirs(root string) bool {
+	only := true
+	_ = filepath.Walk(root, func(p string, fi os.FileInfo, err error) error {
+		if err != nil {
+			only = false
+			return filepath.SkipDir
+		}
+		if !fi.IsDir() && !(filepath.Dir(p) == root && fi.Name() == keptMarkerFile) {
+			only = false
+			return filepath.SkipDir
+		}
+		return nil
+	})
+	return only
+}
+
+// RunAfterLoad runs the app's `after_load:` once, after a Load, when the app is running (waits up to
+// wait). Logged by name either way; a failure is reported, never retried.
+func (m *Manager) RunAfterLoad(name string, wait time.Duration) (bool, error) {
+	st, ok := m.GetStack(name)
+	if !ok {
+		return false, fmt.Errorf("stack %q not found", name)
+	}
+	al := st.Meta.AfterLoad
+	if al == nil || al.Service == "" || len(al.Command) == 0 {
+		return false, nil
+	}
+	deadline := time.Now().Add(wait)
+	for {
+		_ = m.RefreshStatus()
+		if s, ok := m.GetStack(name); ok && (s.State == StateRunning || s.State == StateUnhealthy) {
+			break
+		}
+		if time.Now().After(deadline) {
+			return true, fmt.Errorf("the app did not start within %s — after_load not run", wait)
+		}
+		time.Sleep(5 * time.Second)
+	}
+	return true, m.runAfterLoadNow(name)
+}
+
+// runAfterLoadNow runs the declared command once, now (RunAfterLoad has waited for the app).
+func (m *Manager) runAfterLoadNow(name string) error {
+	st, ok := m.GetStack(name)
+	if !ok || st.Meta.AfterLoad == nil {
+		return nil
+	}
+	al := st.Meta.AfterLoad
+	dir := filepath.Dir(st.ComposePath)
+	args := []string{"exec", "-T"}
+	if al.User != "" {
+		args = append(args, "-u", al.User)
+	}
+	args = append(args, al.Service)
+	args = append(args, al.Command...)
+	t0 := time.Now()
+	out, err := m.afterLoadExec(dir, args...)
+	m.logger.Printf("[INFO] [stacks] after_load %s: %s %v in %s (err=%v): %s", name, al.Service, al.Command, time.Since(t0).Round(time.Millisecond), err, truncateStr(out, 400))
+	return err
+}
+
+// afterLoadExec is the exec seam; production runs compose with the app's env.
+func (m *Manager) afterLoadExec(dir string, args ...string) (string, error) {
+	if m.afterLoadFn != nil {
+		return m.afterLoadFn(dir, args...)
+	}
+	return m.composeExecCustomEnv(dir, m.stackEnv(dir), args...)
+}
+
+var keptTZ *time.Location
+
+func getTimezone() *time.Location {
+	if keptTZ == nil {
+		if loc, err := time.LoadLocation("Europe/Budapest"); err == nil {
+			keptTZ = loc
+		} else {
+			keptTZ = time.UTC
+		}
+	}
+	return keptTZ
+}
+
+// removeEmptyDirs removes root and every directory under it that is EMPTY — never a file, never a
+// directory holding one (os.Remove refuses a non-empty directory). Deepest first.
+func removeEmptyDirs(root string) {
+	var dirs []string
+	_ = filepath.Walk(root, func(p string, fi os.FileInfo, err error) error {
+		if err == nil && fi.IsDir() {
+			dirs = append(dirs, p)
+		}
+		return nil
+	})
+	for i := len(dirs) - 1; i >= 0; i-- {
+		_ = os.Remove(dirs[i])
+	}
+}
+
+// DirSizeBytes is the size seam's value for one folder (du -sb; 0 when unreadable).
+func DirSizeBytes(p string) int64 { return sizeFn(p) }
+
+// DirModTime is a folder's modification time (zero when unreadable).
+func DirModTime(p string) time.Time {
+	fi, err := os.Stat(p)
+	if err != nil {
+		return time.Time{}
+	}
+	return fi.ModTime()
+}