43 lines
3.3 KiB
Markdown
43 lines
3.3 KiB
Markdown
# REPORT — intermediary-mount re-architecture (controller half) → v0.67.5 (2026-06-15)
|
|
|
|
## Type
|
|
Controller half of the intermediary-mount re-architecture (pairs with agent v0.35.1 + catalog repoint).
|
|
Built + Linux-gated (`go vet`/`go test ./...` green) + deployed to demo guest 9201, which was then
|
|
migrated live. Drives are now visible in-guest ONLY at the STABLE path `/mnt/felhom-drives/<name>` (the
|
|
host swaps the backing drive underneath it — no per-drive `pct` mp, no guest reboot for attach/detach).
|
|
Design: `felhom.eu/documentation/audits/SPIKE-intermediary-mount-2026-06-15.md`.
|
|
|
|
## What changed (internal/web/intermediary.go + storage_handlers.go + api/router.go + settings.go)
|
|
- **HDD_PATH repoint.** The registered storage path + every app's HDD_PATH + FileBrowser source are now
|
|
the stable `/mnt/felhom-drives/<name>`; the AGENT still operates on the raw `/mnt/<name>` (mapped via
|
|
`agentWhere()` at the assign/attach/eject/decommission call sites). Enroll binds-under-the-parent
|
|
BEFORE register (the controller only sees the drive at the stable path post-attach). New
|
|
`settings.RepointStoragePath`; `agentapi.DiskInfo` gains `GuestPath`/`BoundUnderParent`.
|
|
- **Drive-absent GATE** (`planDriveGates` pure core + `driveGateLoop` 30s, replacing the retired
|
|
watchdog). An ABSENT external drive (only `/mnt/felhom-drives/<name>` paths — never SSD/system) stops +
|
|
blocks its apps (`StoppedStacks` = gate-stopped set); a RETURNED drive re-attaches + auto-restarts
|
|
them. `present` keys on `BoundUnderParent` (guest-usable), not host-mount. Start-gate in `actionStack`
|
|
refuses to start an app whose drive is absent.
|
|
- **Guest-reboot convergence** (`recreateBootStaleApps`, one-time at startup after a bounded stack-scan
|
|
wait): docker auto-starts app containers on a guest reboot possibly before the agent re-propagates the
|
|
drive, so they bind the empty stable dir; the controller (which restarts with the guest) recreates
|
|
present drive-backed apps that are boot-stale/exited/restarting onto the populated path.
|
|
- **H1 endpoints routed** (were 404): `POST /api/storage/{disconnect,reconnect,restart-apps}` → host-side
|
|
eject/reconnect (no guest reboot).
|
|
|
|
Version path v0.67.0 → .5 (`.1` gate-only-externals, `.2` BoundUnderParent, `.3`/`.4`/`.5` startup
|
|
recreate hardening). Non-hollow tests + companions: `TestPlanDriveGates` (5 states incl. SSD-never-gated),
|
|
`TestAgentWhere`, `TestRunStorageInit_Success` (agent gets RAW, registry gets STABLE).
|
|
|
|
## Live migration (guest 9201) + verification
|
|
8 deployed apps (all on felhom-flash) repointed (app.yaml HDD_PATH rewrite + controller-driven
|
|
down/up recreate, which decrypts the `ENC:` secrets) + registry repointed + FileBrowser re-synced + the
|
|
legacy `mp2` deleted. **A guest reboot self-converges**: the startup recreate logged + rebound the
|
|
drive-backed apps onto `/mnt/felhom-drives/felhom-flash` with no manual intervention. End state: **25
|
|
containers healthy** (komga healthcheck pre-existing quirk), confinement + data integrity verified.
|
|
|
|
## Known residuals (documented)
|
|
- Startup recreate is state-sampled; an app cleanly stopped at the exact sample instant may need one
|
|
manual start (1/8 once). Deterministic fix = a guest-boot-id signal from the agent (future).
|
|
- felhom-usb left on its legacy bind (no deployed apps + stale `decommissioned` intent).
|