controller v0.67.0: intermediary-mount — HDD_PATH repoint + drive-absent gate + H1 routes

Drives are visible in-guest only at the STABLE /mnt/felhom-drives/<name>; the
registered path + HDD_PATH + FileBrowser source repoint there while agent calls
map back to raw /mnt/<name> (agentWhere). Enroll binds-under-parent before
register. Drive-absent GATE (planDriveGates + 30s driveGateLoop) stops/blocks
apps when a drive vanishes and auto-restarts on return; start-gate refuses start
when the drive is absent. H1 endpoints (disconnect/reconnect/restart-apps) routed
onto host-side ops. Non-hollow tests + companions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

controller/internal/web/intermediary.go

@@ -0,0 +1,264 @@
+package web
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"path"
+	"strings"
+	"time"
+
+	"gitea.dooplex.hu/admin/felhom-controller/internal/agentapi"
+	"gitea.dooplex.hu/admin/felhom-controller/internal/settings"
+)
+
+// Intermediary-mount model (controller side). Post-migration a drive is visible in the guest ONLY at its
+// STABLE path /mnt/felhom-drives/<name> (the host swaps the backing drive underneath it; see the agent's
+// internal/localapi/intermediary.go + SPIKE-intermediary-mount). So:
+//   - the REGISTERED storage path + every app's HDD_PATH + FileBrowser source = the STABLE path;
+//   - the AGENT still operates on the RAW /mnt/<name> host PVE mount (assign/attach/eject/decommission),
+//     so controller→agent `where` is mapped back to raw via agentWhere().
+// The drive-absent GATE stops + blocks apps when their drive vanishes and auto-restarts them when it
+// returns (host-side, no guest reboot).
+
+// StableParentDir is the permanent in-guest parent the agent binds drives under (mirrors
+// localapi.StableParentDir).
+const StableParentDir = "/mnt/felhom-drives"
+
+// stablePathForName maps a drive name to its registered stable in-guest path.
+func stablePathForName(name string) string { return StableParentDir + "/" + name }
+
+// agentWhere maps a registered storage path — stable /mnt/felhom-drives/<name> OR a legacy raw /mnt/<name>
+// — to the RAW /mnt/<name> host mount the agent operates on. Idempotent for an already-raw path
+// (path.Base drops the directory either way).
+func agentWhere(registeredPath string) string {
+	name := path.Base(strings.TrimRight(registeredPath, "/"))
+	if name == "" || name == "." || name == "/" {
+		return registeredPath
+	}
+	return "/mnt/" + name
+}
+
+// appsOnStoragePath returns the deployed stack names whose HDD_PATH equals the given (stable) storage
+// path — the apps that depend on that drive.
+func (s *Server) appsOnStoragePath(storagePath string) []string {
+	var names []string
+	for _, st := range s.stackMgr.GetStacks() {
+		if cfg := s.stackMgr.LoadAppConfigByName(st.Name); cfg != nil && cfg.Env["HDD_PATH"] == storagePath {
+			names = append(names, st.Name)
+		}
+	}
+	return names
+}
+
+// stopAppsOnPath stops every deployed app on the given storage path and returns their names (the
+// gate-stopped set — distinct from a user stop, which never enters this set). Best-effort per app.
+func (s *Server) stopAppsOnPath(storagePath string) []string {
+	var stopped []string
+	for _, name := range s.appsOnStoragePath(storagePath) {
+		if err := s.stackMgr.StopStack(name); err != nil {
+			s.logger.Printf("[WARN] [gate] stop %s on absent %s: %v", name, storagePath, err)
+			continue
+		}
+		stopped = append(stopped, name)
+	}
+	return stopped
+}
+
+// restartStacks starts each named stack (the gate-stopped set on drive return). Best-effort per app.
+func (s *Server) restartStacks(names []string) {
+	for _, name := range names {
+		if err := s.stackMgr.StartStack(name); err != nil {
+			s.logger.Printf("[WARN] [gate] restart %s: %v", name, err)
+		}
+	}
+}
+
+// gateAction is the reconcile's decision for one registered storage path.
+type gateAction struct {
+	Path   string
+	Stop   bool   // drive ABSENT + not yet marked → stop apps, mark disconnected
+	Return bool   // drive RETURNED (present + currently disconnected) → re-attach, restart, clear
+	Raw    string // raw /mnt/<name> for the re-attach
+}
+
+// planDriveGates is the PURE decision core: given the registry + the agent's disk list, decide per path
+// whether to gate (stop) or un-gate (return). A drive is "present" iff a disk with a matching GuestPath
+// (stable) or MountPath (legacy raw) is State=="attached". Decommissioned paths are skipped (handled by
+// the decommission flow, not the transient gate). No side effects → unit-testable.
+func planDriveGates(paths []settings.StoragePath, disks []agentapi.DiskInfo) []gateAction {
+	present := map[string]bool{}
+	rawByPath := map[string]string{}
+	for _, d := range disks {
+		live := d.State == "attached"
+		if d.GuestPath != "" {
+			present[d.GuestPath] = present[d.GuestPath] || live
+			rawByPath[d.GuestPath] = d.MountPath
+		}
+		if d.MountPath != "" { // legacy: a raw path registered directly
+			present[d.MountPath] = present[d.MountPath] || live
+			rawByPath[d.MountPath] = d.MountPath
+		}
+	}
+	var actions []gateAction
+	for _, sp := range paths {
+		if sp.Decommissioned {
+			continue
+		}
+		switch {
+		case !present[sp.Path] && !sp.Disconnected:
+			actions = append(actions, gateAction{Path: sp.Path, Stop: true})
+		case present[sp.Path] && sp.Disconnected:
+			actions = append(actions, gateAction{Path: sp.Path, Return: true, Raw: rawByPath[sp.Path]})
+		}
+	}
+	return actions
+}
+
+// ReconcileDriveGates enforces the drive-absent gate: an ABSENT registered drive gets its apps STOPPED +
+// recorded (disconnected); a RETURNED drive gets re-bound under the parent and its gate-stopped apps
+// restarted. Best-effort + idempotent — safe to call on a timer and on demand.
+func (s *Server) ReconcileDriveGates() {
+	if s.settings == nil || s.stackMgr == nil {
+		return
+	}
+	agent, err := s.agentClient()
+	if err != nil {
+		return
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+	resp, err := agent.Disks(ctx)
+	if err != nil {
+		return
+	}
+	for _, a := range planDriveGates(s.settings.GetStoragePaths(), resp.Disks) {
+		switch {
+		case a.Stop:
+			stopped := s.stopAppsOnPath(a.Path)
+			if err := s.settings.SetDisconnected(a.Path, true, stopped); err != nil {
+				s.logger.Printf("[WARN] [gate] mark disconnected %s: %v", a.Path, err)
+			}
+			s.logger.Printf("[WARN] [gate] drive ABSENT %s — stopped+blocked %d app(s): %v", a.Path, len(stopped), stopped)
+			go s.SyncFileBrowserMounts()
+		case a.Return:
+			if a.Raw != "" {
+				if err := agent.GuestAttach(ctx, a.Raw); err != nil {
+					s.logger.Printf("[WARN] [gate] re-attach %s (raw %s): %v", a.Path, a.Raw, err)
+				}
+			}
+			var stopped []string
+			for _, sp := range s.settings.GetStoragePaths() {
+				if sp.Path == a.Path {
+					stopped = sp.StoppedStacks
+				}
+			}
+			s.restartStacks(stopped)
+			if err := s.settings.ClearDisconnected(a.Path); err != nil {
+				s.logger.Printf("[WARN] [gate] clear disconnected %s: %v", a.Path, err)
+			}
+			s.logger.Printf("[INFO] [gate] drive RETURNED %s — re-attached + restarted gate-stopped apps", a.Path)
+			go s.SyncFileBrowserMounts()
+		}
+	}
+}
+
+// driveGateLoop runs ReconcileDriveGates on a timer (the periodic absent/return detector — the slice-8C
+// watchdog was retired). Started as a goroutine at server startup.
+func (s *Server) driveGateLoop() {
+	t := time.NewTicker(30 * time.Second)
+	defer t.Stop()
+	for range t.C {
+		s.ReconcileDriveGates()
+	}
+}
+
+// ---- H1 endpoints (the UI's settings.js calls these; previously 404/unrouted) -----------------
+
+// handleStorageDisconnect EJECTS a drive without restart: stop its apps (gate-stopped), agent-detach the
+// felhom-data bind from under the parent (live, fail-closed), and mark it disconnected. The drive is then
+// safely removable. POST {where} where = the registered (stable) path.
+func (s *Server) handleStorageDisconnect(w http.ResponseWriter, r *http.Request) {
+	where, ok := s.gateWhere(w, r)
+	if !ok {
+		return
+	}
+	stopped := s.stopAppsOnPath(where)
+	agent, err := s.agentClient()
+	if err == nil {
+		if _, derr := agent.EjectDisk(r.Context(), agentWhere(where)); derr != nil {
+			s.logger.Printf("[WARN] [web] disconnect: agent detach %s failed: %v", where, derr)
+		}
+	}
+	if err := s.settings.SetDisconnected(where, true, stopped); err != nil {
+		writeDiskJSON(w, http.StatusInternalServerError, false, err.Error(), nil)
+		return
+	}
+	go s.SyncFileBrowserMounts()
+	writeDiskJSON(w, http.StatusOK, true, "", map[string]any{"where": where, "stopped": stopped})
+}
+
+// handleStorageReconnect re-attaches a returned drive without restart: agent-attach the felhom-data bind
+// under the parent (live), restart the gate-stopped apps, clear the disconnected mark.
+func (s *Server) handleStorageReconnect(w http.ResponseWriter, r *http.Request) {
+	where, ok := s.gateWhere(w, r)
+	if !ok {
+		return
+	}
+	var stopped []string
+	for _, sp := range s.settings.GetStoragePaths() {
+		if sp.Path == where {
+			stopped = sp.StoppedStacks
+		}
+	}
+	agent, err := s.agentClient()
+	if err != nil {
+		writeDiskJSON(w, http.StatusServiceUnavailable, false, err.Error(), nil)
+		return
+	}
+	if aerr := agent.GuestAttach(r.Context(), agentWhere(where)); aerr != nil {
+		writeDiskJSON(w, http.StatusBadGateway, false, "újracsatolás sikertelen: "+aerr.Error(), nil)
+		return
+	}
+	s.restartStacks(stopped)
+	if err := s.settings.ClearDisconnected(where); err != nil {
+		writeDiskJSON(w, http.StatusInternalServerError, false, err.Error(), nil)
+		return
+	}
+	go s.SyncFileBrowserMounts()
+	writeDiskJSON(w, http.StatusOK, true, "", map[string]any{"where": where, "restarted": stopped})
+}
+
+// handleStorageRestartApps restarts the gate-stopped apps on a path (without changing connection state) —
+// the manual "restart the apps that were stopped" action.
+func (s *Server) handleStorageRestartApps(w http.ResponseWriter, r *http.Request) {
+	where, ok := s.gateWhere(w, r)
+	if !ok {
+		return
+	}
+	var stopped []string
+	for _, sp := range s.settings.GetStoragePaths() {
+		if sp.Path == where {
+			stopped = sp.StoppedStacks
+		}
+	}
+	s.restartStacks(stopped)
+	writeDiskJSON(w, http.StatusOK, true, "", map[string]any{"where": where, "restarted": stopped})
+}
+
+// gateWhere decodes + validates the {where} body shared by the H1 endpoints.
+func (s *Server) gateWhere(w http.ResponseWriter, r *http.Request) (string, bool) {
+	var req struct {
+		Where string `json:"where"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeDiskJSON(w, http.StatusBadRequest, false, "érvénytelen kérés", nil)
+		return "", false
+	}
+	where := path.Clean(strings.TrimSpace(req.Where))
+	if where == "" || where == "." || !strings.HasPrefix(where, "/mnt/") {
+		writeDiskJSON(w, http.StatusBadRequest, false, "érvénytelen csatlakoztatási pont", nil)
+		return "", false
+	}
+	return where, true
+}

controller/internal/web/intermediary_test.go

@@ -0,0 +1,69 @@
+package web
+
+import (
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-controller/internal/agentapi"
+	"gitea.dooplex.hu/admin/felhom-controller/internal/settings"
+)
+
+func TestAgentWhere(t *testing.T) {
+	cases := map[string]string{
+		"/mnt/felhom-drives/felhom-usb": "/mnt/felhom-usb", // stable → raw
+		"/mnt/felhom-usb":               "/mnt/felhom-usb", // legacy raw → raw (idempotent)
+		"/mnt/felhom-drives/x":          "/mnt/x",
+	}
+	for in, want := range cases {
+		if got := agentWhere(in); got != want {
+			t.Errorf("agentWhere(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestStablePathForName(t *testing.T) {
+	if got := stablePathForName("felhom-usb"); got != "/mnt/felhom-drives/felhom-usb" {
+		t.Errorf("stablePathForName = %q", got)
+	}
+}
+
+// TestPlanDriveGates pins the gate's pure decision across the four meaningful states.
+//
+// COMPANION GUARD: a trivial impl that gates every absent path regardless of the disconnected flag would
+// re-stop an already-disconnected drive (and never return it); one that ignores presence would never
+// gate. Both fail here.
+func TestPlanDriveGates(t *testing.T) {
+	paths := []settings.StoragePath{
+		{Path: "/mnt/felhom-drives/usb"},                          // present + connected → no action
+		{Path: "/mnt/felhom-drives/flash"},                        // ABSENT + connected → STOP
+		{Path: "/mnt/felhom-drives/back", Disconnected: true},     // present + disconnected → RETURN
+		{Path: "/mnt/felhom-drives/gone", Disconnected: true},     // ABSENT + disconnected → no action (steady)
+		{Path: "/mnt/felhom-drives/dead", Decommissioned: true},   // decommissioned → never touched
+	}
+	disks := []agentapi.DiskInfo{
+		{MountPath: "/mnt/usb", GuestPath: "/mnt/felhom-drives/usb", State: "attached"},
+		{MountPath: "/mnt/back", GuestPath: "/mnt/felhom-drives/back", State: "attached"},
+		// flash + gone + dead report NO present disk
+	}
+	actions := map[string]gateAction{}
+	for _, a := range planDriveGates(paths, disks) {
+		actions[a.Path] = a
+	}
+	if len(actions) != 2 {
+		t.Fatalf("expected exactly 2 actions (stop flash, return back), got %d: %+v", len(actions), actions)
+	}
+	if a, ok := actions["/mnt/felhom-drives/flash"]; !ok || !a.Stop || a.Return {
+		t.Errorf("flash should STOP (absent+connected): %+v", a)
+	}
+	if a, ok := actions["/mnt/felhom-drives/back"]; !ok || !a.Return || a.Stop || a.Raw != "/mnt/back" {
+		t.Errorf("back should RETURN with raw /mnt/back (present+disconnected): %+v", a)
+	}
+	if _, gated := actions["/mnt/felhom-drives/usb"]; gated {
+		t.Errorf("usb (present+connected) must not be gated")
+	}
+	if _, acted := actions["/mnt/felhom-drives/gone"]; acted {
+		t.Errorf("gone (absent+already-disconnected) is steady — no action")
+	}
+	if _, acted := actions["/mnt/felhom-drives/dead"]; acted {
+		t.Errorf("decommissioned drive must never be gated")
+	}
+}

controller/internal/web/server.go

@@ -104,6 +104,10 @@ func NewServer(cfg *config.Config, stackMgr *stacks.Manager, cpuCollector *syste
 
 	s.loadTemplates()
 	go s.cleanupSessions()
+	// Drive-absent gate reconcile (intermediary-mount model): the periodic absent/return detector that
+	// replaced the retired slice-8C watchdog. Stops+blocks apps whose drive vanished, auto-restarts them
+	// when it returns. No-op when the agent is unreachable.
+	go s.driveGateLoop()
 
 	// Log auth source on startup
 	if sett != nil && sett.GetPasswordHash() != "" {

controller/internal/web/storage_handlers.go

@@ -116,15 +116,19 @@ func (s *Server) runStorageInit(ctx context.Context, agent diskAgent, device, fs
 	if uuid == "" {
 		return storageInitResult{}, fmt.Errorf("formázás kész, de az új fájlrendszer-azonosító nem feloldható — frissítsen és használja a Csatolás funkciót")
 	}
-	// 3. Mount (benign assign) + 4. register.
+	// 3. Mount (benign assign) at the raw /mnt/<name>. 4. Bind felhom-data under the shared parent FIRST
+	// (intermediary model) so the drive's STABLE path is live in the guest, THEN register + skeleton there
+	// (the controller can only see/write the drive at the stable path post-attach). 5. Register the stable
+	// path — that is what apps' HDD_PATH / FileBrowser / monitoring use.
 	if err := agent.AssignDisk(ctx, uuid, where, fstype, ""); err != nil {
 		return storageInitResult{}, fmt.Errorf("csatlakoztatás sikertelen: %w", err)
 	}
-	if err := s.registerStoragePath(where, label, setDefault); err != nil {
+	s.attachIntoGuest(ctx, agent, where)
+	stable := stablePathForName(path.Base(where))
+	if err := s.registerStoragePath(stable, label, setDefault); err != nil {
 		return storageInitResult{}, err
 	}
-	s.attachIntoGuest(ctx, agent, where)
-	return storageInitResult{Registered: true, Where: where}, nil
+	return storageInitResult{Registered: true, Where: stable}, nil
 }
 
 // attachIntoGuest passes an enrolled drive INTO the guest (slice 10 P2) so the controller + apps can
@@ -152,11 +156,12 @@ func (s *Server) runStorageAttach(ctx context.Context, agent diskAgent, device,
 	if err := agent.AssignDisk(ctx, uuid, where, fstype, ""); err != nil {
 		return storageInitResult{}, fmt.Errorf("csatlakoztatás sikertelen: %w", err)
 	}
-	if err := s.registerStoragePath(where, label, setDefault); err != nil {
+	s.attachIntoGuest(ctx, agent, where)
+	stable := stablePathForName(path.Base(where))
+	if err := s.registerStoragePath(stable, label, setDefault); err != nil {
 		return storageInitResult{}, err
 	}
-	s.attachIntoGuest(ctx, agent, where)
-	return storageInitResult{Registered: true, Where: where}, nil
+	return storageInitResult{Registered: true, Where: stable}, nil
 }
 
 // pendingActivationDrives returns registered storage paths that are NOT yet live-mounted in this
@@ -288,6 +293,12 @@ func (s *Server) ServeStorageAPI(w http.ResponseWriter, r *http.Request) {
 		s.handleStorageMigrateStatus(w, r)
 	case r.URL.Path == "/api/storage/decommission" && r.Method == http.MethodPost:
 		s.handleStorageDecommission(w, r)
+	case r.URL.Path == "/api/storage/disconnect" && r.Method == http.MethodPost:
+		s.handleStorageDisconnect(w, r)
+	case r.URL.Path == "/api/storage/reconnect" && r.Method == http.MethodPost:
+		s.handleStorageReconnect(w, r)
+	case r.URL.Path == "/api/storage/restart-apps" && r.Method == http.MethodPost:
+		s.handleStorageRestartApps(w, r)
 	default:
 		http.NotFound(w, r)
 	}
@@ -421,7 +432,8 @@ func (s *Server) finalizeDecommissionWith(ctx context.Context, agent diskAgent,
 	if err := s.settings.SetDecommissioned(where, migratedTo); err != nil {
 		return fmt.Errorf("nyilvántartás frissítése sikertelen: %w", err)
 	}
-	if _, err := agent.Decommission(ctx, where); err != nil {
+	// Registered path is the STABLE /mnt/felhom-drives/<name>; the agent decommissions the raw mount.
+	if _, err := agent.Decommission(ctx, agentWhere(where)); err != nil {
 		return fmt.Errorf("a meghajtó leszerelése sikertelen: %w", err)
 	}
 	if s.stackMgr != nil {
@@ -715,7 +727,8 @@ func (s *Server) handleStorageEject(w http.ResponseWriter, r *http.Request) {
 		writeDiskJSON(w, http.StatusServiceUnavailable, false, err.Error(), nil)
 		return
 	}
-	res, err := agent.EjectDisk(r.Context(), req.Where)
+	// The registered path is the STABLE /mnt/felhom-drives/<name>; the agent operates on the raw mount.
+	res, err := agent.EjectDisk(r.Context(), agentWhere(req.Where))
 	if err != nil {
 		writeDiskJSON(w, http.StatusBadGateway, false, err.Error(), nil)
 		return

controller/internal/web/storage_handlers_test.go

@@ -168,19 +168,24 @@ func TestRunStorageInit_Success(t *testing.T) {
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if !res.Registered || res.Where != "/mnt/hdd1" {
-		t.Fatalf("expected registered at /mnt/hdd1, got %+v", res)
+	// Intermediary model: the AGENT operates on the RAW /mnt/hdd1 (assign + guest-attach), but the
+	// REGISTERED path (+ HDD_PATH/FileBrowser) is the STABLE /mnt/felhom-drives/hdd1.
+	//
+	// COMPANION GUARD: a pre-fix impl that registered the raw /mnt/hdd1, or that passed the stable path to
+	// the agent, would fail one of these assertions.
+	if !res.Registered || res.Where != "/mnt/felhom-drives/hdd1" {
+		t.Fatalf("expected registered at the STABLE /mnt/felhom-drives/hdd1, got %+v", res)
 	}
 	if len(agent.assignCalls) != 1 || agent.assignCalls[0].uuid != "NEW-9999" || agent.assignCalls[0].where != "/mnt/hdd1" {
-		t.Fatalf("assign must use the resolved fs UUID + mount path: %+v", agent.assignCalls)
+		t.Fatalf("assign must use the resolved fs UUID + RAW mount path: %+v", agent.assignCalls)
 	}
 	paths := s.settings.GetStoragePaths()
-	if len(paths) != 1 || paths[0].Path != "/mnt/hdd1" || paths[0].Label != "Külső HDD" || !paths[0].IsDefault || !paths[0].Schedulable {
-		t.Fatalf("StoragePath not registered as expected: %+v", paths)
+	if len(paths) != 1 || paths[0].Path != "/mnt/felhom-drives/hdd1" || paths[0].Label != "Külső HDD" || !paths[0].IsDefault || !paths[0].Schedulable {
+		t.Fatalf("StoragePath not registered at the stable path as expected: %+v", paths)
 	}
-	// P2C: enroll must pass the drive into the guest.
+	// Enroll must pass the drive into the guest via the RAW path (the agent maps it under the parent).
 	if len(agent.guestAttachCalls) != 1 || agent.guestAttachCalls[0] != "/mnt/hdd1" {
-		t.Fatalf("enroll did not guest-attach the drive: %+v", agent.guestAttachCalls)
+		t.Fatalf("enroll did not guest-attach the raw drive path: %+v", agent.guestAttachCalls)
 	}
 }