site serve and site view: run a site's own preview app in the VM and forward it to the hypervisor #242
No reviewers
Labels
No labels
blocked
bug
decision
duplicate
enhancement
help wanted
invalid
landed?
question
ready-to-merge
stale
wontfix
bug
duplicate
enhancement
help wanted
invalid
question
wontfix
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
allod/tools!242
Loading…
Reference in a new issue
No description provided.
Delete branch "agent/site-preview-unit"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
allod site serve, which replacesallod site preview, runs whatever a site's own flake callspreview, as a user service inside the VM, and the newallod site viewon the hypervisor forwards that one port to the owner's browser until Ctrl-C. The part an agent can run is tested against real Nix and systemd; the part that crosses from the hypervisor to the VM has only been checked by its argument lists and is the owner's to run before merging.allod site previewis gone, andallod site servetakes its place without starting zola. It takes--port,--stop,--vmand a site id, and the old flags--interface,--base-url,--drafts,--openand the pass-through after--are gone. Existing zola sites stop previewing until their flake has apreviewapp; the owner accepted that on the issue.allod site viewis new, in every build.deploy,checkandconfig, and what every other command gets from the registry, shown by a test with a malformed port beside a healthy entry.allodhands tosystemd-run,systemctl,journalctl,nix,gitandssh; a script run in a dev VM starts, finds, fails and stops real previews, 9 steps of 9.systemctl --user stop 'allod-preview-*'in the VM; it listens on loopback only.viewon the hypervisor can work, becauseviewrunsallod site serve <site>in the VM.Closes allod/tools#240
Risk
R3. The change starts systemd user units, opens SSH connections from the hypervisor, and changes the decoder every registry lookup in
allodgoes through. The worst credible failures after validation: a preview reported as serving when it is not; a server left running on loopback in a VM; a forward on the hypervisor's loopback that outlives its use until the terminal closes. None touches a secret, a deployed site, or state that cannot be rebuilt. What keeps it at R3 and not lower is that--vmandviewcannot be run by an agent.For the owner to run on the hypervisor
After the VM runs this build and a site has a
previewapp and apreview_port:allod site view <site>shows the page in the browser at the printed address.docs/allod-site-preview.md, checking after each that the hypervisor's port is free and that the VM is in the state the table says. This includes the two questions still unmeasured: whetherssh -Nexits when the VM shuts down or the link drops, and how soon.allod site serve --stop --vm <vm> <site>stops the server from outside.Validation
Run by the overseer on
4807f62, the final commit, which ismastermerged into the branch:nix build .#checks.x86_64-linux.go-checks -L --no-link --rebuild: exit 0,cmd/allodokunder all four tag combinations.nix flake check:all checks passed!.ALLOD_UNDER_TEST=<built binary> bash tests/site-preview-by-hand.sh:all 9 steps passed, noallod-preview-*unit and no listener left.--stopfor a site whose registry port is the string"18650"reports not running, exit 0; with the user manager unreachable it says systemd could not be asked, exit 1;viewfor a site with no port is refused by name;--vm -xis refused.Run by the implementing worker and read from its captured output, not repeated by the overseer:
TestSiteServeVM,TestSiteViewForwardsThePortandTestSiteViewVMLookup. Moving the address ahead of the question about the unit failsTestSiteServeOutcomes/unit_gone_although_the_port_answered.systemctl --user is-active --quietexits 0 for an active unit, 3 for a failed or activating one, 4 for one that is inactive or does not exist, 1 when the manager cannot be reached.Measured before the code was written, recorded on the issue:
nix runof a site's app works inside the unit; zola 0.23.6, live-server 0.11.1 and Vite 7.3.6 each hold one listener on the page port and deliver their reload message through a relay of that single port;systemctl --userworks in a non-interactivessh <vm> <command>andallodis on its path.Not run:
--vmandviewagainst a real VM. This VM's key is not authorized to log in to the VM itself.Review
One cold pass by
gpt-5.6-solthroughcodex exec, reasoning efforthigh, on6bdfffd, read-only. Eleven findings; each was checked against the source. One fix round,260e719. The rename that followed,f0b415b, and the merge ofmaster,4807f62, change no behavior of these commands and were not reviewed again.--stopand defeats--portpreviewandview--stopis-activereads as not runninglist-units ... || truehides a failed probeviewprints the address beforesshhas bound the portsshreports a taken port itselfThe reviewer's list of comments that restate code was applied in the same round.
Known limits
acme/siteandacme-site, share a unit name.nix runwrites aflake.lockinto a site checkout that has none.npm installat every start and writes about 21 MB ofnode_modules/into the checkout.Size
The issue's numbers were called an estimate by the owner on the issue. Against them:
site_serve.go256,site_view.go81,registry.go51 addedsite_serve_test.go455,site_view_test.go215docs/allod-site-preview.mdtests/site-preview-by-hand.shThe Go above the estimate is the worktree lookup and the refusals the issue did not count: a missing app, a malformed registry port, a path nix cannot be given, a user manager that cannot be asked, and the unit asked about again after its port answers. Each has a test that pins it.
Departures from the issue's text
All are recorded on the issue.
git rev-parse. The check for the app therefore runs only when a start is about to happen.--stopasks whether the unit is there before stopping it:systemctl --user stopexits 5 for a unit that is not loaded.allod site serve, notallod site preview, at the owner's request on this pull request. The nounpreviewstays for the flake app,preview_port, theALLOD_PREVIEW_*variables and the unit name.allod site previewis an unknown command, pinned byTestSiteServeOldNameIsUnknown.Two defects the overseer reproduced on the previous commit. A repository entry whose 'preview_port' held a string, a fraction or null failed json.Unmarshal for the whole registry, so registryEntries returned nothing and every lookup in the file missed — including the ones commands that have nothing to do with sites make. The field is now decoded late, from json.RawMessage, and one that is present and outside 1024-65535 is refused by name. An absent or null one still means "no port". Measured: a sibling entry resolves while the mistyped site is refused as allod: preview_port "18650" for fixture/site in <registry> is not a whole number from 1024 to 65535 A checkout path is interpolated into Nix source, inside a quoted string, and again into '<root>#preview', where '#' and '?' have their own meaning; 'nix eval --expr' cannot take it as an argument instead. One check now refuses a path holding anything but letters, digits, '/', '.', '_', '+' and '-', naming the path and the character, before any command runs. previewPortValue in registry.go is the one definition of the range, so '--port' and a registry value are held to it in the same place. Refs allod/tools#240Requested by the owner: rename the command
allod site previewtoallod site serve.The reason given:
previewnames what the owner gets, not what the command does, and it reads like something that shows a page, which isview's job.serveis the verb the site tools use for this (zola serve,hugo serve) and says a server is running and listening.Only the command word changes.
--stopstays a flag of it. The noun stayspreviewwherever it names the thing being served: the flake appapps.<system>.preview, the registry fieldpreview_port,ALLOD_PREVIEW_PORTandALLOD_PREVIEW_INTERFACE, and the unit nameallod-preview-<slug>. allod/inventory#17 is unaffected.site preview: run the site's own preview app as a user unit, and site view to forward itto site serve and site view: run a site's own preview app in the VM and forward it to the hypervisormasterwas merged into this branch, at the owner's request to bring it up to date. The branch is a merge and not a rebase becauseagent/*branches take new commits only.Two things needed a hand:
README.md: both sides changed thecmd/allod/line of the layout. The result namescheck, frommaster, andsite serve and view, from this branch.cmd/allod/main_test.gogained the test helperequalArgs.master's newcheck_test.gouses it, and its only definition was insite_preview_test.go, which this branch replaces. Git merged the two without a conflict and the Go checks then failed withundefined: equalArgs.Run on the merged tree: the Go checks pass under all four tag combinations,
nix flake checkprintsall checks passed!, andtests/site-preview-by-hand.shpasses 9 of 9.allodlists bothcheckandsite.