felhom-controller/REPORT.md

REPORT — v0.151.0: Megosztás status contract (S-1 + S-4 core) + connect-address card (S-2 + S-5)

Date: 2026-07-20 · Repo: felhom-controller (v0.150.0 → v0.151.0) · Trunk, pushed to main. Origin: felhom.eu/documentation/audits/DIAG-sharing-2026-07-20.md. Class: implementation (code + tests + build + deploy + live verify). S-3 (no mDNS) deliberately out of scope — it awaits Viktor's two Mac probes and is an image change, not a controller one.

Baselines used

Repo	start main @	end main @	version
felhom-controller	8db9232 (== origin/main, clean tree)	badf17b	v0.150.0 → v0.151.0
felhom.eu	0c48869	eaa2173	docs only

Deployed at start: felhom-controller:0.150.0 on guest 9201 — verified Up (healthy), not assumed.

§4.1 — what b5d78d1 actually intended, and what became of it

Read in full before touching the coercion. It was defensive, not a fix for a named repro: the v0.147.0 commit message describes slice 4b as detached-and-polled bring-up feedback and never mentions a status-contradiction bug, and the code's own comment states the intent outright — „A stale idle/running job must never contradict reality: liveness wins on a fresh page."

That intent is legitimate and survives; it was simply asserted on the wrong channel. Liveness is already carried by the running field in the same JSON object, which is where a LEVEL belongs. So instead of a repro-derived regression test there is a named test on that field: TestSharingStatus_LivenessStillReportedWithoutAnyJob asserts that with no job in memory at all, running tracks SambaRunning() in both directions — exactly the guarantee the coercion was written to provide, minus the phase-channel side effect that produced the loop.

Files changed (all in commit badf17b)

File	Change
controller/internal/web/sharing_handlers.go	A.1 coercion deleted + the two-channel contract documented; B page data gains SMBDirectAddress (enabled-only); sambaLANAddress() seam resolver; SMBRunning gains the nil-manager guard the status handler already had
controller/internal/web/samba_ensure_job.go	A.2 consumeIfRunning() — serve-once for terminal running, and only while the single-flight slot is free
controller/internal/web/server.go	sambaAddrFn seam field
controller/internal/web/templates/sharing.html	B.2 „Csatlakozás a megosztáshoz" section — markup only
controller/internal/stacks/samba.go	SambaLANAddress() + the sambaLANAddr() seam + the pure parseIPv4FromIPAddrOutput
controller/internal/stacks/manager.go	sambaAddrFn field; SetSambaRunProbe (exported seam setter — internal/web's tests need a live-container world from another package, same precedent as SetMigrationDoneHook)
controller/internal/infra/samba.go	SambaHostInterface — single source for the nic named by smb.conf's interfaces =, the container's FELHOM_IFACE, and the address read
new web/sharing_status_contract_test.go, web/sharing_connect_card_test.go, stacks/samba_lanaddr_test.go	Scenarios A/B/C/D + the parser matrix
CHANGELOG.md, REUSE.md, controller/README.md, REPORT.md, CONTEXT.md	docs

Test results

23/23 packages green, run twice — the second run with -count=1 (no cache). Package count unchanged: this task added tests, not packages.

Test	Scenario
TestSharingStatus_SteadyStateProducesNoEdge	A — two polls, live container, empty slot → phase:"idle", running:true both times
TestSharingStatus_LivenessStillReportedWithoutAnyJob	the b5d78d1 intent regression (both liveness directions)
TestSharingStatus_RealBringUpServedExactlyOnce	B — first poll running, second idle, running:true on both
TestSharingStatus_RunningNotConsumedWhileInFlight	the in-flight window: not consumed while the slot is held, served once after release()
TestSharingStatus_NonEdgePhasesStaySticky	C — failed/needs_password/pulling/starting each persist over 3 polls
TestSharingStatus_EnvelopeShapeUnchanged	exactly the 3 keys phase/error/running
TestSharingStatus_NilStackManagerIsQuiet	a nil manager does not panic the poll
TestSharingConnectCard_ShowsNameAndDirectAddress	D — Windows + Mac + direct forms present, seam invoked on this render
TestSharingConnectCard_AddressDerivedFreshEveryRender	D — one derivation per render; a changed address reaches the page
TestSharingConnectCard_NoAddressOmitsTheLine	D — "" omits the address block, keeps the name lines
TestSharingConnectCard_UsesConfiguredName	D — OTTHON renders and FELHOM appears nowhere
TestSharingConnectCard_AbsentWhenSharingDisabled	card gated on the feature; zero derivations when off
TestSharingConnectCard_UnsetNameFallsBackToEffective	unset name → the effective default, never an empty smb://
TestParseIPv4FromIPAddrOutput	3 accepted forms (incl. verbatim live output) + 8 rejected (link-local, unspecified, loopback-only, IPv6-only, docker error text, …)
TestSambaLANAddressFailsQuiet	error → "", address → passthrough

Red-proofs (§10) — all three mutated → FAILED → restored → green

#	Mutation	Result
A	reinstated if phase == idle && running { phase = running }	TestSharingStatus_SteadyStateProducesNoEdge FAILED — call 1: phase = "running", want "idle", and again on call 2. Restored → green.
B	deleted the s.cur = nil serve-once clear	TestSharingStatus_RealBringUpServedExactlyOnce FAILED — second call: phase = "running", want "idle"; TestSharingStatus_RunningNotConsumedWhileInFlight also failed at its post-release assertion. Restored → green.
D	replaced fresh derivation with a package-level cached value	TestSharingConnectCard_AddressDerivedFreshEveryRender FAILED on all three assertions — total derivations = 1, want 2, the new address absent, the old address still on the page. Restored → green.

Other gates

template_id_gate · emoji_gate · native_confirm_gate · offbox_rename_gate — all OK.

sharing.html's <script> block is byte-identical to v0.150.0 — verified by extracting the block from git show HEAD:… and from the working tree and comparing (one block each, equal). Both fixes are server-side, so the client contract is proven fixed rather than worked around.

Deploy

./build.sh 0.151.0 --push   → sha256:0141b62fe64e3d471446d8a1a8c1a719b3669dab26888e50acbf13644677510b, 145M
docker ps --filter name=felhom-controller --format '{{.Image}} {{.Status}}'
gitea.dooplex.hu/admin/felhom-controller:0.151.0 Up 26 seconds (healthy)

Clean-tree gate held before the build: git status --porcelain empty, HEAD == origin/main.

Live validation

Method: endpoint-level — the exact endpoints the UI invokes, so no server logic is skipped, only rendering. claude-in-chrome is not available on DooPlex.

1. GET /sharing/status ×3, authenticated → {"data":{"error":"","phase":"idle","running":true},"ok":true} on all three calls. Before the fix the same call returned phase:"running" every time. The client's reload path is reachable only from phase === "running", so this is the server-side proof that the loop's trigger is gone.
2. GET /sharing, authenticated → the connect card is present (2 Csatlakoz hits — the heading and the Mac line) showing smb://FELHOM and smb://192.168.0.104. That address is the guest's real current DHCP lease and is a DERIVED value: it matches what ip -4 -o addr show eth0 reports inside the samba container, and it exists as a literal nowhere in the codebase. Grepped with ASCII-safe substrings per the CLAUDE.md trap.
3. Human check — OPEN, Viktor's to give: that the page visibly sits still. A browser is the one method not available here.

DIAG finding-status flips (felhom.eu@eaa2173)

S-1 → FIXED v0.151.0 · S-2 → SHIPPED v0.151.0 · S-4 → CORE SHIPPED v0.151.0 (the unified async-job layer stays R-45, which gained a one-line note recording the lesson) · S-5 → SHIPPED v0.151.0 · S-3 → OPEN, awaiting smbutil lookup FELHOM and dns-sd -B _smb._tcp from the Mac.

Observations — noticed, not acted on

• The poll timer's idle path. tick() does call stop() in the idle branch, so on a steady-state page the interval now ends after the first response — but the .catch() branch deliberately keeps polling on a transient failure, so a page whose status endpoint is erroring polls forever at 1.5 s. Recorded, not fixed: the JS was read-only in this task, and this is the next thing anyone auditing that block will ask about.
• Multi-tab success banner. With two /sharing tabs open during a real bring-up, only the tab that polls first sees „A megosztási szolgáltatás fut." Accepted, and documented at the method itself; both tabs still show the true state, which comes from the running level and the server-rendered badge.
• SMBRunning in sharingPageData had no nil-manager guard while the status handler beside it did. Added (one != nil) — noted because it is the only change in this task not traceable to a DIAG finding.
• setup.DetectLocalIPs is the same problem answered differently. It needs a HOST_IP env var because the controller sits on a docker bridge; the new read goes through the samba container instead, which needs no env plumbing but only works while sharing is up. Neither is wrong — worth knowing both exist if a third caller ever wants a guest IP.
• The samba container has no ps (found while establishing what the exec path could rely on) but does have /sbin/ip. Any future in-container probe should verify its tool the way the catalog healthcheck rule already requires.
• The .162 half of the original report is still worth a product answer. The connect card now gives customers the right address, but nothing stops a stale saved favourite on the Mac from failing silently forever. Out of scope here; it is the kind of thing the S-3 mDNS work would make moot by putting the box in the Finder sidebar.