felhom-controller/REPORT.md

# REPORT — NAS network storage Part A2 (controller registry/UI/health), v0.92.0

**Date:** 2026-06-30
**Task:** `TASK.md` — NAS Part A2 (+ hub dispatcher critical-severity fix, "Part 0"). Implementation class.

## Baselines

| Repo | before → after |
|------|----------------|
| felhom-controller | v0.91.0 → **v0.92.0** (commit `364dc50`) |
| felhom.eu (hub, Part 0) | v0.23.0 → **v0.24.0** (code `0ff1d3c`, manifest `87f0794`) |
| felhom-agent | v0.50.0 (A1, unchanged) |

## What was built

The controller side of NAS network storage: an operator adds a customer's NAS share and points a media app
at it, all via the UI — proxying to the validated agent foundation (A1 `/netstorage/*`). A NAS is a
**distinct "network" storage kind**, NOT a drive: no enroll/eject/decommission/migrate/wipe/SMART.

### Part 0 — hub dispatcher (felhom.eu, v0.24.0, commit `0ff1d3c`)
- `internal/notify/dispatcher.go` `ProcessEvent`: routed only `warning`/`error` → a `critical`-severity
  event was **silently dropped**. Now routes `warning`/`error`/`critical` (`severityNotifies`); an
  unrecognized severity is **logged**, not dropped; `info` stays a deliberate non-notify.
- `host_disk_critical` now emits its **natural `critical` severity** (`FormatOperatorEmail` styles it 🔴).
- **Latent crash guard:** `processCustomer` dereferenced `GetNotificationPrefs`, which returns `(nil,nil)`
  for a customer with no notification row — an event for such a customer would have **panicked/crashed the
  hub**. Now guards `prefs == nil`.
- Verified safe first (§9 rule 5): **no** controller event emits `critical` (all info/warning/error), so no
  surprise alert volume. Tests: `severityNotifies` + companion (pre-fix predicate drops `critical`),
  ProcessEvent routes `critical`, unknown logged, info silent.

### A2 — controller (v0.92.0, commit `364dc50`)
- `internal/agentapi/client.go`: `AddNetStorage`/`ListNetStorage`/`RemoveNetStorage` + `NetworkMountStatus`
  mirror. **SMB credential passes straight through to the agent (0600 file); never persisted by the
  controller.**
- `internal/settings/settings.go`: `StoragePath.Kind` discriminator + network descriptors (no password);
  `IsNetwork()`/`IsNetworkStoragePath()`; `NetworkMountRoot`.
- `internal/web/netstorage_handlers.go` (NEW): `POST /api/storage/netstorage/{add,remove}` + `GET`; registers
  a Kind=network `StoragePath`; merges the agent's live per-share health.
- **Kind-gating (safety centerpiece):** `refuseNetworkLifecycle` blocks the drive ops (eject/decommission/
  migrate/wipe) on a network path; the drive-absent gate (`planDriveGates`) and the missing-storage surface
  **skip network paths** → an `unreachable` NAS is a recoverable warning, never the drive stop-cascade.
  `networkStorageWarnings` drives a distinct app-card badge.
- UI (`settings.html`): a "Hálózati tárhely (NAS)" section (add form NFS/SMB, health badges, remove); shares
  auto-selectable as a media app's `HDD_PATH`.

## Tests — both repos `go build ./... && go vet ./... && go test ./...` GREEN
- agentapi: round-trip (creds forwarded, mapping/protocol forwarded, health states; `idle`/`ok` not
  degraded, `unreachable` degraded).
- registry **Kind-gate companion**: the drive-lifecycle handlers refuse a network path (400 before any
  agent/stackMgr use); a DRIVE path is NOT gate-refused (proves the gate keys on Kind, not the path).
- **`unreachable`≠`missing` companion**: a network path is never "missing"; the drive gate produces NO Stop
  action for an absent network path, while it DOES for an absent drive path under the same parent.
- Part 0 dispatcher tests (above).

## Live e2e validation (against the isolated sim NAS)

**Method:** the demo controller has no password set, so CSRF is skipped — I drove the **exact UI endpoints**
(`/api/storage/netstorage/*`) via curl from inside guest 9201's controller container (the full controller
server pipeline runs; an acceptable proxy per CLAUDE.md). The storage-page badge was verified from the
rendered HTML. **Sim NAS** = a throwaway privileged LXC (NFS, `anonuid/anongid=101000`, own config) on
felhom-pve — never touched production storage; destroyed after.

- **A — add via controller:** `POST /api/storage/netstorage/add` (nfs) → `registered:true`, registered as
  `/mnt/felhom-drives/media kind=network sched=True proto=nfs`; the agent mounted it; `GET` showed health
  `idle` then `ok` after first access. The share is absent from `/api/disks` (distinct class).
- **B — media app reads from NAS:** jellyfin (uid 1000, healthy) bound to the controller-registered NAS path
  **read the media library** (`Movies/SampleMovie (2024).mkv` owned `1000:1000` via the +100000 idmap, plus
  `readme.txt`). (jellyfin isn't in the app catalog — run as a raw uid-1000 container to exercise the real
  A1 chain; see Observations.)
- **C — NAS disappears (no cascade):** black-holed the sim → `GET /api/storage/netstorage` health
  `unreachable` in ~2s; the settings page rendered the "Nem elérhető" badge in the "Hálózati tárhely (NAS)"
  section; **guest + controller + jellyfin stayed healthy**; over a drive-gate tick the network path was
  **NOT** marked disconnected and **no app was stopped** (cascade prevented). On NAS return → health `ok`,
  no remount.
- **D — remove via controller:** `POST /api/storage/netstorage/remove` → `removed:true`, list empty, host
  units gone + unmounted.
- **E — Part 0:** unit-validated (critical routes; companion proves the pre-fix drop); hub v0.24.0 deployed
  via ArgoCD (Synced/Healthy), `host_disk` now emits natural `critical`. (Not re-fired live — the demo host
  root is at 24% after the prior task's prune, below threshold.)

Deployed: hub v0.24.0 (ArgoCD sync, Synced/Healthy); controller v0.92.0 on guest 9201
(`docker ps … :0.92.0 Up (healthy)`, clean logs). Sim NAS + test jellyfin torn down; `/mnt/felhom-drives`
back to only the real drives.

## Observations / limitations
- **Part B (restic-over-SFTP NAS backup target)** still pending — separate task.
- **No media app in the catalog** (jellyfin/immich/…): A2's HDD_PATH selectability is wired (the NAS path is
  Schedulable and appears in the dropdown), but the full "deploy a catalog media app onto the NAS via the
  deploy flow" couldn't run; jellyfin was a raw uid-1000 container for the read proof. Adding jellyfin to
  `app-catalog-felhom.eu` is a small follow-up that would make the app-card badge live-exercisable too.
- **Mixed-uid share sharing** is a documented v1 limit (a share's +100000 uid mapping is fixed at add-time →
  one app or same-uid apps).
- **Write apps on a soft NFS NAS:** a mid-disappearance in-flight file can truncate (spike) → prefer
  atomic-write apps or SSD-staging; v1 test used a READ app (jellyfin).
- Per-storage worst-fill alerting (hub host_disk follow-on) still pending.

No secrets in any committed file. SMB/NFS test credentials were throwaway and out-of-band only.