felhom-controller/REPORT.md

REPORT — v0.128.0: chunked browser .fab upload on /import (tunnel-proof)

Date: 2026-07-13 · Version: controller v0.128.0 (baseline v0.127.3 59e4ca7 reconfirmed against live Gitea; local == origin/main) · Commit db16371 on main · MinAgent unchanged (no agent coupling — the feature is controller-local fs + HTTP). Implements TASK-fab-browser-upload (ruling F3 2026-07-13: chunked).

Step-0 probe — the Cloudflare edge cap, measured on the REAL tunnel (before any code)

Probe	Result
POST 120 MiB (zeros) → https://felhom.demo-felhom.eu/step0-cap-probe	HTTP 413 "Payload Too Large" from the edge (Server: cloudflare, CF-RAY a1aa78cd1f04324d-VIE, cloudflare-branded HTML body). Rejected on the declared Content-Length: only ~1.1 MB left the client, 0.41 s.
POST 80 MiB, same target	HTTP 302 → /login?next=… — the controller's auth redirect, i.e. the origin was reached (edge passage PROVEN). 0.48 s; the origin answered before consuming the body (unauth redirect), so no full-upload throughput datum — the edge decision is header-based, which is the datum that matters.

Gotcha recorded: local DNS (192.168.0.250) overrides felhom.demo-felhom.eu to the LAN guest (192.168.0.139), and curl's default Expect: 100-continue lets the server answer before the body is sent — the honest probe needed --resolve onto Cloudflare's public IP (172.67.149.59) plus -H "Expect:". Outcome: cap confirmed at ~100 MB → uploadChunkBytes = 64 MiB (the spec's default), server-side per-request cap 96 MiB.

What shipped

• controller/internal/web/handler_export_upload.go (new) — POST /api/export/upload/{init,chunk,finalize,abort} inside ServeExportAPI (inherits the main.go RequireAuth(CsrfProtect(...)) mount — nothing added at the mux). Single-flight slot (netstorage-job shape); init sanitizes to a [A-Za-z0-9._ -] base name + mandatory .fab, free-space gate (declared + 1 GiB margin, Hungarian error with both numbers); chunk requires offset == received (else 409 + received_bytes echo) and streams via io.Copy; finalize = exact declared size (else 422 + .part deleted) → fsync → atomic rename, collision → lowest-free "name (N).fab" computed from the ORIGINAL name (never (1)(1)); abort deletes the .part. Startup GC sweeps *.part-* on every registered drive (wired in main.go after SetAppExporter); 15-min idle timer aborts server-side. No client-side sha256 — deliberate, rationale in the file header (WebCrypto can't stream-hash multi-GB; .fab self-validates at import).
• controller/internal/appexport/estimate.go — diskFree exported as DiskFree (REUSE.md row added); web seam uploadDiskFree package var.
• controller/internal/web/templates/app_import.html — upload zone above the bundle list (drag-and-drop + "Fájl kiválasztása", accept=".fab"), progress "Feltöltés: {pct}% ({done} / {total} GB)" + "Megszakítás", spec'd Hungarian error strings; File.slice sequential loop with one retry per chunk re-synced from the 409 echo; on success the page reloads (the EXISTING scan renders the row — no second lister). Copy-by-hand hint now names BOTH paths. Gates green: template_id, emoji, native_confirm, mojibake.

Tests (all green; full module go build && go vet && go test ./... = 23 packages ok)

Scenario	Test	Result
A happy path (3 chunks byte-exact, existing scan lists it, no .part residue)	TestFabUpload_HappyPath	PASS
B offset replay → 409 + echo, disk unchanged, re-sync continues	TestFabUpload_OffsetMismatchRejected	PASS
C traversal neutered inside exports; ext/charset/hidden refused; oversize (faked statfs) → Hungarian msg with 3.0/2.0 GB; 2nd init → 409	TestFabUpload_SecurityGates	PASS
C route wrap (unauth POST → 401 on all four paths via the main.go-shaped mount)	TestFabUpload_MountInheritsAuth	PASS
D finalize size mismatch → 422, .part deleted, slot freed	TestFabUpload_FinalizeSizeMismatch	PASS
E startup GC removes stray .part, keeps real bundles; idle-expiry deletes + frees slot	TestFabUpload_GCAndIdleTimeout	PASS
F collision → app (1).fab, re-run → app (2).fab, original bytes untouched	TestFabUpload_CollisionLowestFreeSuffix	PASS
abort deletes .part + frees slot	TestFabUpload_Abort	PASS

Red-proofs (§10, all run + reverted, git diff clean):

• C — sanitize bypassed (raw client filename used): TestFabUpload_SecurityGates FAILED with "sanitized upload must land inside the exports dir" (the file materialized at the traversal target {drive}/evil.fab).
• B — offset check removed (append regardless): TestFabUpload_OffsetMismatchRejected FAILED with "replay: got 200, want 409".
• F — naive overwrite (rename straight to the requested name): TestFabUpload_CollisionLowestFreeSuffix FAILED with first collision landed as "app.fab", want "app (1).fab".

Deploy + live verification

• Image gitea.dooplex.hu/admin/felhom-controller:0.128.0 (sha256:4c943ea1…) built on 180.
• Demo guest 9201: Up … (healthy) on 0.128.0; selfupdate log confirms "Current version 0.128.0 is up to date"; no ERROR/FATAL. Drill guest (nested PVE 192.168.0.152, guest 9201): Up … (healthy) on 0.128.0.
• Route live-checked on the deployed box: unauthenticated POST /api/export/upload/init → 401 JSON both via LAN and through the real Cloudflare edge (--resolve onto 172.67.149.59) — the new path is deployed and auth+CSRF-wrapped on the customer path.

NOT live-validated (Viktor's ~5-minute leg)

The end-to-end multi-GB browser upload through the real tunnel needs a dashboard login (CC has no customer session). Suggested test: export a real app to .fab, download it via the browser, re-upload it on /import, import it — the full circle. Everything beneath the login was exercised: edge cap probed, endpoints tested A–F, deployed route answers through the tunnel.

Observations

• The per-drive target picker was deliberately left out (v1 = default drive only, per §12); if a customer keeps exports on a non-default drive, the upload still lands on the default one and the scan shows both — acceptable, but a picker is the natural follow-up.
• controller/cmd/controller is matched by a gitignore rule — main.go changes need git add -f (it IS tracked; add refuses the path without -f).
• Startup GC logs only when it removes something; the clean deploy logged nothing (expected).