felhom-controller/controller/internal/stacks/kept.go

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 == "" || st.Protected {
			continue
		}
		// v0.274.0 (found live on 9202): only an app whose definition binds its drive folder THROUGH
		// ${HDD_PATH} can own one. The file browser's own compose binds every kept folder by its absolute
		// path (the read-only view), and matched first — the list named romm's and paperless's leftovers
		// "Filebrowser". Pinned by TestKept_OwnerIsNeverTheFileBrowser.
		if b, err := os.ReadFile(st.ComposePath); err != nil || !strings.Contains(string(b), "${HDD_PATH}") {
			continue
		}
		for _, p := range ParseComposeHDDMounts(st.ComposePath, drive) {
			// the folder itself, or one inside it (paperless binds appdata/paperless/media and …/export)
			if c := filepath.Clean(p); c == abs || strings.HasPrefix(c, abs+string(filepath.Separator)) {
				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())
				// R-695 (v0.275.0): an EMPTY dated folder is not kept data — it is what Docker leaves when a
				// file-browser bind outlives a Delete (it recreates the missing source, empty, as root).
				// Listed, it was bound again, and the bind recreated it: a loop. Never listed, never bound.
				if !dirHasEntries(dir) {
					continue
				}
				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()
}