| title | The structure test and owners |
|---|---|
| explainer | The code's shape, and one owner for each concern |
| weight | 3 |
internal/structure parses every Go file in the repo, tests and every platform's included, generated files left out, and checks what linters don't. mise run test runs it. Each failure starts with its rule and the file and line:
| Rule | Checks |
|---|---|
max-methods |
no type has more than 24 methods, value and pointer receivers together, and no interface declares more than 24, not counting the interfaces it embeds; a larger one splits by what its methods do |
no-init |
no func init() |
package-vars |
a package-level var is a blank interface check, an Err*/err* sentinel from errors.New or fmt.Errorf, a regexp.MustCompile, template.Must or sync.Once* result, a //go:embed file, or listed in allowedVars; anything else becomes a field, a const or a local |
layers |
which packages import which, in non-test files (tests may wire packages together) |
owners |
in non-test files, only its owner runs a host command that commands lists, only the files execSites lists make a host command, only guardOwner asserts a backend package's type, only envOwner reads a DEVVM_ variable, but the settings envSettings lists, only its file in envOwners reads HOME, only its owner's string literals hold a text that literals lists, only its owner's string literals are, whole, a name that names lists, only its owner's calls to package strings split or join on a separator that separators lists, only pathsOwner builds a path in devvm's data or config folder, and only its file in callers calls a function that callers lists (details) |
goroutines |
in non-test files, a function that starts a goroutine, with a go statement, a wait group's Go or time's or context's AfterFunc, is in goroutineSites, with what waits for its goroutines to end, or detached: and why nothing does, and a package that starts one calls leaktest.Main in its tests' TestMain |
dropped-errors |
in non-test files, no function assigns a Wait's error, or a strconv parse's, to _, such as _ = cmd.Wait() or n, _ := strconv.Atoi(s), unless droppedErrors lists it with why, because a failed wait would read as a clean exit and text that isn't a number as 0 |
read-limits |
in non-test files, every io.ReadAll reads through an io.LimitReader made in its call, such as io.ReadAll(io.LimitReader(r, limit+1)), unless unboundedReads lists its function with why, so a peer or a file that never ends can't fill the memory |
The layers:
- Only
cmd/devvmandinternal/cliimportinternal/ui; onlyinternal/cliimportsinternal/vm; onlycmd/devvmimportsinternal/cli. internal/backend/...imports none ofinternal/vm,build,tools,netpolicy,secrets,project,gitprotect,sshconfig,sshagent,trustorvmssh, so the port forwarder and the link sessions stay devvm's on every backend.- Only
internal/backend/registryandinternal/cliimport a backend (lima); only tests importbackendtest,internal/leaktest,internal/memnet, andinternal/stubtestand the packages below it, which import onlyinternal/msgand each other. The stubs' binary,internal/stubtest/stub, and its state,internal/stubtest/stubstate, import nothing else of devvm's, because the binary stands in for the tools devvm runs and is built apart from it. internal/proxyimports no other devvm package butinternal/daemon,internal/landlock,internal/redact,internal/safefileandinternal/vmname.assets,locales,internal/platform,internal/msg/gen,internal/testbuild,internal/hostgit,internal/shell,internal/vmname,internal/daemon,internal/fetch,internal/jsonc,internal/redact,internal/agents,internal/safefile,internal/landlock,internal/leaktestandinternal/memnetimport no devvm package;internal/agentloginonlyinternal/agents,internal/fetch,internal/jsonc,internal/proxy,internal/redact,internal/safefileandinternal/state, because it holds agents' logins;internal/msgonlylocalesandinternal/vmname;internal/pathsonlyinternal/msgandinternal/vmname;internal/stateonlyinternal/msg,internal/paths,internal/platformandinternal/vmname;internal/imageonlyassets,internal/agents,internal/msg,internal/pathsandinternal/shell;internal/devcontaineronlyinternal/image,internal/jsonc,internal/msgandinternal/shell.
Everything it holds the code to is in devvm() in internal/structure/structure_test.go:
largeTypeslists the types allowed more methods, which arepaths.Dirsandui.UI, each with its count as its maximum and why. A backend isn't one of them, because its methods are split bybackend.Backend's roles (how a backend plugs in). One that grows fails; one that shrinks fails until its maximum is lowered.allowedVarslists the other package-level vars, by package folder and name, each with why: values set by-ldflags, fixed tables, test fixtures. An entry whose var is gone fails.layersis the layering table: a layer's packages (from, but notexceptFrom) import none ofto(butexceptTo);x/...isxand the packages below it.commandsmaps a host command to the one package that runs it.execSiteslists the files that make a host command withexec.Commandorexec.CommandContext, each with why, and a listed file that no longer makes one fails.guardOwnernamesinternal/backend/guard.go, the one file that asserts a backend's type.envOwnernames the one file that reads devvm'sDEVVM_variables.envSettingslists the variables read elsewhere, each with the files that read it and why. A listed file that no longer reads its variable fails.envOwnersmaps another variable to the one file that reads it, which forHOMEisinternal/paths/dirs.go.literalsmaps a text that only one package's string literals may hold to that package and what the others use instead.namesmaps a name that only one package's string literals may be, whole, to that package and what the others use, andnamesFreelists the folders whose literals may be one anyway:internal/stubtest, whose stubs are named after the commands they stand in for.goroutineSiteslists every function outside tests that starts a goroutine, as its file and its name (internal/proxy/splice.go: splice, orType.Methodfor a method), with a function literal's goroutine counted in the function it's in, or in the package-level var whose value it is. A goroutine starts with agostatement, a wait group'sGo, ortime's orcontext'sAfterFunc, whose function runs in a goroutine of its own. Goroutines the standard library starts otherwise, such as an HTTP server's for each connection, are the leak checks' to find, not the registry's. Each entry says what waits for the goroutines to end, such asscanAll's wg.Wait, or starts withdetached:and says why nothing does and what ends them anyway, such as a look at a folder whose disk may hang, whichfolderWithinleaves to finish on its own. A new goroutine fails until its function is listed, and a listed function that no longer starts one fails, so the list stays current. A package that starts a goroutine also fails until a test file of its callsleaktest.Main. The tests' own goroutines are the leak checks'.droppedErrorslists the functions outside tests that assign aWait's or astrconvparse's error to_, by the same name asgoroutineSites, each with why, and none does today. The check reads no types, so a call of any method namedWaitcounts, and the parses areAtoi, theParsefunctions,Unquote,UnquoteCharandQuotedPrefix. A listed function that no longer drops one fails, so the list stays current.unboundedReadslists the functions outside tests whoseio.ReadAllreads with no limit, in the same way, each with why its reader ends: the status line's look at the end of the run's own log, which only that run writes, and the test stubs' reads of the standard input that devvm under test writes and closes. A reader limited before the call, held in a variable, counts as unlimited, so the limit goes in the call itself. A listed function that no longer reads with no limit fails.callersmaps a function to the one file outside its package that calls it, and a listed file that no longer calls it fails. A method is listed aspkg.Type.Name, such asinternal/paths.Dirs.AgentSettings, and any call of a method by that name outside its package counts, because the check reads no types, so a listed method's name is its type's alone.
TestRulesFail breaks each rule, and each layer, on small sources and checks the failure names it.
Shell scripts that live in Go strings get shellcheck too, since lint's shellcheck only finds files with a shebang. TestEmbeddedScripts in internal/structure finds every call site that runs a script as sh -c, /bin/sh -c or bash -c (or -lc), in a []string literal or a call's arguments, outside tests and the stubs. When the script is a constant, a literal, or a sum of them, such as seedApply with seedMarker in it, the test writes it to a file and runs shellcheck -s sh or -s bash, as its shell reads it, at -S warning, skipping when shellcheck isn't installed. A script built at run time can't be read there, so the test fails on one until dynamicScripts lists its file and expression with why: a fixed command around quoted paths, a devcontainer's own command, or a builder that a test of its package checks, as internal/vm's TestBuiltScriptsShellcheck does for the scripts built from the agents' registry. A listed site that's gone fails too, so the list stays current. A shell given any other flag, such as sh -ec or sh -e -c, fails as well, because the test would miss its script: put options such as set -e in the script instead. -s, for a script on standard input, is fine.
Each concern in devvm has one owner, the package or function that does it, such as internal/hostgit for every git command devvm runs on the host, internal/paths for every folder and file devvm uses, internal/settings for every default (settings.Read and settings.Save, over config.toml and settings.json, with each value's parser), and locales/en.toml for every message. Before you add a helper, a parser, a path, a file reader, a message or a table, find its owner and extend it. A second copy drifts from the first, and then one of them is wrong. Code with no owner yet can have a second copy, because a copy can be cheaper than the wrong shared helper, so extract an owner at the third copy, or at once for a judge such as proxy.Public or NormHost, whose two copies would disagree on what's allowed. The packages says what each package owns, and the failures of the checks below name the owners too.
Each package owns these concerns, and a package's doc.go, where it has one, maps the package itself. internal/fetch, internal/redact, internal/agents, internal/jsonc, internal/shell, internal/vmname, internal/safefile, internal/landlock and internal/daemon use the standard library alone, and internal/proxy uses it with internal/daemon, internal/landlock, internal/redact, internal/safefile and internal/vmname and nothing else. internal/devcontainer imports no module from outside devvm, but it uses internal/image, internal/jsonc, internal/msg and internal/shell.
| Package | Owns |
|---|---|
cmd/devvm |
the entry point: ui.Main makes the run's UI and runs the root command with it, and it's the only os.Exit |
internal/cli |
the command line. Each Cobra command has a file of its own, and its about holds its docs page, its help group and the reason it has no --json. The package also holds the run's services (app.go), the argument and flag checks, whose failures are usage errors, help, --json, the CLI tests, docgen/, which writes the CLI reference, and doctor's check of Linux's pins (pins.go) |
internal/vm |
what each command does to a folder's VM, below the command line: Env and its parts, the one start, the finder, the inventory, Launch, the agents' store, logins and saves, Lifecycle and the one remake, Housekeeping, Settings, Net and Links, which its doc.go maps with their owners. A --clone VM's copy is cloneseed.go's: its in-VM scripts initRepos, seedStage and seedApply, sent through the backend's Exec, with the shallow file read through internal/safefile and the pack made by internal/hostgit's git. Its uncommitted changes are cloneworktree.go's seedTree: the index read through internal/safefile and normalised by internal/hostgit's git, hostgit.DiffFiles for what differs, and each working copy read through a safefile.Root, opening each folder from its parent with OpenDir, so no link on the way is followed, then the record of what went, which clonecheck.go reads back. An operation in progress, the info files and the stash are clonestate.go's seedState, each file read through internal/safefile, and only the files its stateIDs lists are read for object ids. The settings and hooks are cloneconfig.go's seedConfig, an allowlist of config keys whose URLs cleanURL takes the credentials out of, and a VM's stash entry is saved by clonesave.go, without its untracked files |
internal/shell |
quoting for a POSIX shell (Quote, QuoteJoin), a word on one line for bash (QuoteLine, ANSI-C quoting) and a shell variable's names (EnvName), with the standard library alone |
internal/vmname |
the name of every machine devvm runs on a backend, VM, which a field or a parameter holds instead of a string, and the parsers that make one where it's read: Parse for a project VM's name from an argument or a file name, which also reads vm.json's name and runs in project.Nth, ParseListed for one a backend lists, VM's UnmarshalText for one in a JSON file, which may be any machine's, so a field that must hold a project VM's is still checked with IsProject, Image for an image's machine and VM.Aside for a remake's old one. msg.M.VM reads back the VM a message's function took. It also holds a project VM's name grammar (Prefix, HashLen, IsVM, and VM's IsProject, Hash, Slug, Short, ImageKey and a remake's Aside), with the standard library alone, so the proxy uses it too (the checks on owners) |
internal/project |
a project folder: its VM's name, its link targets, the folders that aren't safe to use and its parents |
internal/gitprotect |
.git protection: one scan for each check, a Locker for each host, which is Flags on macOS, Binds on Linux, whose pins the start sets, or else Watch, and the table of its reports |
internal/hostsafety |
the folder's other checks on the host: one Walk once the VM is stopped, which skips .git and finds set-id files and nested repos, and an SSH origin |
internal/hostgit |
every git command devvm runs on the host, with no fsmonitor, hooks, filters or signing programs, ssh only, none of the environment's GIT_* variables and no prompts, and with GIT_NO_REPLACE_OBJECTS=1 and GIT_GRAFT_FILE=/dev/null, so it sees a repo's real history |
internal/sshconfig |
the ssh config that reaches running VMs by name, and its Include line in ~/.ssh/config |
internal/sshagent |
each VM's choice of SSH agent, devvm's own agent and its keys |
internal/build |
building and rebuilding images, and their records |
internal/image |
image keys and names, with no side effects, and the shared tools' registry, SharedTools: one entry for each toolchain, with its members, its detection, its installer, its guest environment, its PATH folders and its version files (the structure test's names) |
internal/fetch |
every HTTP client, with the standard library alone: NewClient, with a timeout and HTTPSOnly or SameScheme, Retry and Transient, ReadCapped, Get, Resolve, which finds where a HEAD's redirects end, and Download, which checks the SHA-256 and caps the size |
internal/upgrade |
devvm upgrade: how this devvm was installed (Detect), the releases (Source, with the newest, Check for a notice, and Fetch, which checks minisign's ED signature by the built-in key, then the SHA-256), the unpack, the link's switch and its rollback, and Homebrew. upgradetest/, for tests only, has a TLS release server and a minisign signer |
internal/from |
--from: references, registry digests with an anonymous token, Docker's IDs and the recorded digests |
internal/redact |
passwords out of logs, with the standard library alone: String for the run log's lines, which takes out proxy keys and URL passwords, In for another program's log as it grows, in place and keeping its length, reading a line not yet ended again from its start when it's within MatchMax of what an earlier look read, else from MatchMax back, starring what runs on to an @ there (Look.Cut does the same after a rotation's cut), and Unended for a copy's cut end; and Secret, the type of the values that let whoever holds them act as you or as a VM (Secrets in the code) |
internal/vmlog |
every log a VM can drive but the proxy's own: Limit, the rate and length of what a VM makes devvm's background processes write, which the port forwarder and the link session write through and whose Allow the link session's warnings take their turns from; Capped, a background process's log held to its cap as it appends, with Trim at its next start; and KeepVM, which the VM's proxy (through proxy.IO.KeepLogs) and a build run on the logs the backend writes as the VM runs (backend.Run.Logs), the serial consoles' among them, each in a goroutine of its own, redacting what each gained every second (redact.In), so a reboot in place can't leave the proxy's password there, and skipping a log that hasn't grown. Redact is Lima's redaction at the end of a start. Each rotation copies the log's end to its .1 file, redacting only what the last look didn't reach and masking a secret cut at its end, and empties it with f.Truncate, counting a log by what it holds past the hole its writer left, as Lima's programs write at their own offset. Every log is opened through safefile (Opts.Write), never through a link or waiting on a FIFO. The proxy, which imports only the standard library and a few of devvm's leaves, rotates its own logs itself (proxy.rotating) |
internal/safefile |
every read of a file a VM can write or swap, with the standard library alone, so the proxy uses it too (the checks on owners) |
internal/landlock |
the proxy's child's confinement on Linux, with the standard library alone, behind its own build tags: Self, which confines every thread of the process to its folders with no_new_privs, Landlock and the hand-written seccomp filter (filter), checks that it holds, and returns what it got (Result), which the proxy's confineSelf turns into its line in run/proxy.confined (proxy.Confinement) (the child's sandbox) |
internal/devcontainer |
a project's devcontainer.json, with no side effects: finding it, mapping it to a new VM's plan, its refusals, and what devvm update's second reading replaces (Reread) |
internal/jsonc |
JSON with comments (jsonc.Strip), with the standard library alone |
internal/tools |
the shared tools: the lock, mise on the host, the daily check, the tool images' builds and the share |
internal/netpolicy |
network policy: the choice of tier, learning the hosts a VM reached, RiskOf, the VM's proxy and the self-check |
internal/secrets |
tokens on the host and the VM's bindings to them, and your own secrets (custom.go, with their checks, Yours and custom-secrets.json) |
internal/trust |
your CAs in ~/.config/devvm/ca, read and checked, sent to VMs, the build VMs' Trust scripts and the guest environment, and each VM's own CA and its next one (InitCA, in vms/<hash>/run/ca/) |
internal/agents |
the coding agents' registry, with the standard library alone: one Def for each agent, with its shared tool, settings, logins, history, guest environment, ways to log in and [pass-keys], which every list of the agents comes from. Code about one agent names it by its constant (the structure test's names) |
internal/agentlogin |
agents' login and settings files on the host: the VM's copies with placeholders, the bindings, the values and the OAuth refresh (File, with a format for each kind of login), the shape of every placeholder (Placeholder), Redact, and Restore, which puts the store's values back for a VM's placeholders |
internal/proxy |
the proxy, which runs as two processes, its broker, devvm _proxy (broker.go, process.go), and its child, devvm _proxy-child (child.go), which talk over a socketpair in the broker's protocol (wire.go), as its README.md describes, the relay of a VM's SSH agent, the only socket of an agent a VM's backend forwards, on paths.Dirs.AgentRelay (Config.Agent, agent.go), and the one form of a host that every package judges and compares hosts in (Host, NormHost, HostOK), which the structure test holds it to (the checks on owners) |
internal/seatbelt |
macOS's sandbox as devvm uses it: sandbox-exec's path (Exec), a Seatbelt string and a real path in a profile (String, Path), the links a sandboxed lookup goes through (Links), and the profile of a VM's proxy's child (ChildProfile), which Sandbox.ProxyChild gives the broker through proxy.IO.Seatbelt, because the proxy imports the standard library alone. Lima's profile for its hostagent (lima/seatbelt.go) is written with the same strings and paths. How the child is confined, its report in run/proxy.confined (proxy.Confinement), the check that it holds (checkConfined) and the hook where a platform confines the child in the process (confineSelf) are internal/proxy's confine.go, which every platform's confinement shares |
internal/daemon |
devvm's background processes, with the standard library alone: detached starts, pid files checked against the process's arguments, stopping with TERM and then KILL, readiness by a status file, the lifeline, and an accept loop's wait after an error that leaves its listener open (AcceptRetry), which the port forwarder, the link session, a login's forward, the proxy's SSH agent relay and the desktop relay share. It's the only place that signals a process by its pid. Processes has what each of those processes holds, reads, writes and is confined by |
internal/desktop |
devvm desktop's relay on the host, which checks VNC's password, then opens an ssh channel to the VM's socket and drops the viewer's clipboard, and the desktop's passwords |
internal/backend |
Backend and its roles, Caps, Require, Check, the registry and its guard (As), as how a backend plugs in describes. Below it are backendtest/, the fake, registry/, which holds every backend, and lima/, whose pins.go has QEMU's user and mount namespace on Linux, its pins, their events and the probe, while platform's pinrun_linux.go is the namespace's side |
internal/vmssh |
devvm's own use of a VM's ssh, on every backend. Checked is the one way to a VM's ssh (how a backend plugs in), and Forwards is the port forwarder's one owner, which locks, stops and starts it with its ports from vm.json. The package also holds a login's forward of this machine's loopback ports, in devvm's own process (ForwardLoopback), the links' sessions, and each VM's one record of its host keys for each start (PinHostKeys, in vms/<hash>/run/known_hosts), which every ssh of devvm's checks |
internal/ui |
the only package that prints: ui.UI, with messages, prompts, the status line, the run log and the cleanups, and ui.Main, which handles signals. It has no package state |
internal/msg, locales |
messages: en.toml, the generated functions, the doc links (docs.go), the generator (gen/), Reporter and Question (messages) |
internal/ports |
a VM's ports section, with the forwards asked for and the host ports chosen, and the one allocator of host ports, under the claims lock, which puts VMs' ssh only on the ports browsers refuse (SSHPorts) |
internal/paths |
every folder and file devvm uses, a VM's in its folder (Dirs.VM, and a project VM's folder, vms/<hash>/, from Dirs.VMDir), and host paths resolved and compared (Physical, PhysicalParent, Within and Below, where resolve.go says which one is for what) |
internal/state |
a VM's state, vm.json, with its core fields and one section for each package, which changes only in VM.Update under the VM's lock. It also owns the layout version (CheckLayout and migrations, while testdata/script/layout.txtar lists every file), every file written whole (WriteFile, WriteFileMode) and private folders (PrivateDir) |
internal/settings |
the defaults (Defaults, Read, Save), with your config.toml, read strictly, over devvm's settings.json, and each value's check (ParsePorts, ParseCPUs, ParseGiB and the retention settings) |
internal/platform |
the code for each system, behind build tags |
internal/ubuntu |
finding Ubuntu's cloud image and verifying it, without ever downloading one |
internal/testbuild |
whether this is a test build, which ldflags set: only a test build reads the test overrides (cli's readOverrides) |
assets |
the files devvm ships, embedded as assets.FS, which cli passes to constructors. base.yaml is base's Lima template, and prelude.sh, with $devvm_arch, $devvm_libc and devvm_sha, comes first in each build script run with bash, the user's layers included, and is put in place of a script's #! line, as one eval line quoted by shell.QuoteLine, by image.WithPrelude, which image.OwnScript calls for devvm's own. layers/ holds base's scripts, its policy and Ubuntu's signing keys, and the built-in layers, desktop, docker and nix, each with its policy. network/ holds the network tiers' own policies, features/ base's optional features, and shared-tools/ its mise.toml, build.sh and *.policy files. guest/ holds the scripts in the VM that every launch sends, and the port forwarder's ports.sh, and oci/ is --from's conversion, as its README.md describes |
internal/structure |
the structure test, for tests only, and owners_doc_test.go, which writes the checks on owners |
internal/stubtest |
the test stubs, for tests only |
internal/leaktest |
the goroutine leak checks, Main for a package's TestMain and Check for one test, for tests only, and the standard library only, so the proxy's tests use it too |
internal/memnet |
the network in memory for tests in a synctest bubble: connections (Pipe) that close their writing side alone, hold a buffer's worth and have deadlines, and listeners by address (Network), for tests only, and the standard library only, so the proxy's tests use it too |
testdata |
the CLI tests (script/*.txtar), the golden fixtures (golden/<os>/), a lock to test with (mise.lock), each package's coverage baseline on each system (coverage/<os>.txt), each release's state fixture (v<release>/<os>/), and the lines that break each forbidigo rule (lint/, Go lint rules) |
tests/e2e, tests/e2e-mise.lock |
the end-to-end tests on real VMs, in Go with the tag e2e and a file for each section. TestE2E is the run, sandbox_test.go has the sandbox, its slot's paths and lock and e2eUbuntuRelease, and slots_test.go runs the slots. The lock file holds the shared tools' versions that every section but tools uses (scripts/bump.sh e2e-tools) |
scripts, packaging, .goreleaser.yaml, VERSION, CHANGELOG.md |
bump.sh updates the pins. release.sh runs the signed tag's checks around GoReleaser, then minisign, and publish.sh makes the release itself, with its checks, release.sh, one yes, then the pushes, gh release and the tap. The test and coverage tasks run test.sh, which runs coverage.sh to check each package's coverage against its baseline. packaging/ holds the Homebrew formula and key.go, which embeds its folder, so devvm upgrade's key is minisign.pub's, and a build without that file has none. Only the scripts read VERSION (releasing) |
install.sh |
curl | bash: it installs the host's archive, with the binary, the README, the changelog and the license, checked, into ~/.local/lib/devvm/<version>, then runs doctor's fixes, asking first. Tests source it (DEVVM_INSTALL_TEST) |
An owner gets a check only when a second copy would be a bug or a security hole, and only when the check is exact, so that it never fails on code that's right. Each check's failure names the owner. The table is written from ownerDocs in internal/structure/owners_doc_test.go, which TestOwnersDoc checks it against and TestOwnersAgree checks against the structure test's own tables, so a change to a check changes its row there, and go test ./internal/structure -run TestOwnersDoc -update writes the table again:
| Check | Owner | Allowed elsewhere |
|---|---|---|
forbidigo, testbuild.On |
internal/cli, whose readOverrides is the only code that asks whether this is a test build |
nowhere: other packages take the overrides as fields |
forbidigo, os.FindProcess, syscall.Kill, unix.Kill and os.Process's Kill and Signal |
internal/daemon, which signals a background process only while its pid file and its arguments say it's still that process (Proc), or through the process it started (Handle) |
internal/platform; tests, which signal the children they started; and a child that hasn't been waited for yet, whose pid is still its own, with a nolint saying so |
forbidigo, unicode.IsGraphic, IsPrint, IsControl and Bidi_Control |
msg.Safe in internal/msg/safe.go, the one rule for which characters reach the terminal, which msg.Printable, msg.OneLine, the UI's renderers and devvm agent save's diff follow, so a second rule can't let through what this one refuses (Colors says what it refuses) |
a check that isn't about the terminal, such as a path one line long, with a //nolint:forbidigo saying so |
| forbidigo, HTTP clients | internal/fetch, whose NewClient sets each client's timeout and redirect policy (HTTPSOnly or SameScheme), and whose Retry, Transient, ReadCapped, Get, Resolve and Download try again after the failures that may pass, cap what a body or a download may hold, follow a HEAD's redirects to where they end and check a download's SHA-256 before anything uses it. fetch.Client is its own type, so a client that NewClient didn't make, such as &fetch.Client{}, fails every request, and a caller changes a client's transport through its Transport method |
internal/proxy, which is the standard library only, and tests, which make their own servers' clients |
forbidigo, netip.Addr's IsPrivate |
proxy.Public in internal/proxy/proxy.go, the one judge of whether an address is on the internet: netip's classes, the table of the other ranges that aren't (notPublic), and the IPv4 address in a NAT64 or 6to4 address. The proxy's floor, devvm network lock, a --clone VM's partial-clone remotes and --from's registries all ask it, so a range added to it holds for each |
internal/proxy |
forbidigo, redact.Secret's Reveal; the structure test, a struct that embeds redact.Secret and an interface that declares Reveal() string |
redact.Secret in internal/redact/secret.go, the type of the values that let whoever holds them act as the user or a VM, but for those Secrets in the code names: a VM's proxy password, a secret's value, a login's keys and tokens once they leave its file, and the company proxy's password and its Proxy-Authorization. Every way of printing one shows <redacted> or, in an unexported field, an address, and encoding one as JSON or text is an error, never a stand-in, so a file that holds the real value writes it through its own wire type, and a value can't be lost by going somewhere it isn't meant to |
where the value is used, each call to Reveal with a //nolint:forbidigo that says why: the proxy's password check, its config file, the headers it puts values in, the company proxy's credentials, the VM's CA key as it signs and the broker's frames to its child; the store's file and Keychain; the VM's proxy URL and its key in vm.json; a login's file, its refresh and its claims; and tests. No struct embeds redact.Secret and no interface declares Reveal() string outside internal/redact |
forbidigo, os.WriteFile, os.Create and os.O_TRUNC |
internal/state, whose WriteFile and WriteFileMode write a file whole through a temporary file in its folder, renamed over it, so a reader never sees half of it |
internal/proxy, which imports only the standard library and has its own writer, writeAtomic; internal/msg/gen, which imports no devvm package; internal/stubtest; tests; and, with a nolint saying why, a file written another way: a log that a process writes as it runs, a download that streams into its file, and internal/daemon's pid and status files, each written in one write that a reader takes as missing until its line ends |
forbidigo, os.Open, os.OpenFile, os.ReadFile, os.OpenRoot, os.OpenInRoot, os.DirFS and os.Root's Open, OpenFile, ReadFile and FS, in the code that reads files a VM can write or swap: internal/gitprotect, internal/agentlogin, internal/vm's devcontainer.go, detect.go, paste.go and agentsave*.go, internal/netpolicy/rules.go, internal/vmlog, and internal/proxy's config.go, policy.go, rotate.go and nixcache.go |
internal/safefile, which imports only the standard library, so the proxy reads with it too. Its Read and Open open a file without blocking and, unless the caller passes Follow, without following a symbolic link at the path's end. They then check the file they opened, not its name, so a FIFO, a device or a folder is refused with ErrNotRegular, a file past its cap with ErrTooLong, and, with OneLink, a file with another hard link with ErrLinked. A FIFO that the VM swaps in after a check can't hold devvm, and a link to /dev/zero can't flood it. Checked checks a file its caller opened another way in the same way, such as devvm paste's copied file, which platform.OpenNoLinks opens following no link but the system's, through openat, which the standard library doesn't have on macOS. OpenRoot opens beneath a folder through os.Root, never through a link out of it, and its FS lists and stats what's there but opens only regular files |
every other file, which is devvm's own or the user's; tests, which make their own fixtures; and, with a nolint saying why, what opens a file to write it or a folder to lock it, such as the proxy's logs and the Nix cache's lock, each opened never through a link or waiting on a FIFO and checked once open |
forbidigo, os.Chmod, os.Chtimes, os.Chown, os.Lchown and os.Truncate, in the code that changes files a VM can write or swap: internal/proxy, internal/vmlog and internal/vmssh |
the file's own descriptor, from internal/safefile, an os.Root or the proxy's OpenLog: os.File's Chmod, Chown and Truncate, an os.Root's methods, and the proxy's touchFile (futimes, or utimensat with no path), because a VM can swap a name for a link between the open and the change, which would then reach a file of yours |
every other package, whose files are devvm's own or the user's; tests, which make their own fixtures; and, with a nolint saying why, a unix socket devvm has just made in its own folder (the proxy's SSH agent relay and the link session's sockets), whose mode only its path can set |
forbidigo, os.Setenv, os.Unsetenv, os.Clearenv and syscall's |
each command's own environment, its exec.Cmd's Env, because every command and background process devvm starts inherits devvm's. A VM's SSH agent is one: the finder's target carries its socket, its proxy's relay (netpolicy.Proxy.Prepare), which goes to the backend in backend.ExecOpts.Agent, backend.ShellOpts.Agent and Confinement.AgentSocket, and Lima sets SSH_AUTH_SOCK on that VM's limactl commands alone, so a run that reaches several VMs never gives one another's |
daemon.Ready in internal/daemon/status.go, which takes the status file's name out of a background process's own environment; stubtest.NoGitRepo, which takes git's variables that pick a repo out of a test's environment until the test ends; and tests, which use t.Setenv |
the structure test's owners, host commands |
the runners: the UI's LoggedCmd, which a package takes as a field and which runs a command into the run log, a backend's Runner, and internal/hostgit. A host command that one of them doesn't run is made only in the files execSites lists: those that make the command a runner then runs, such as Lima's limactl and mise's, and those whose command can't go into the run log, because it streams for as long as a link, the port forwarder or the desktop's relay lasts, asks on the terminal, outlives the run, or carries a secret |
tests |
the structure test's owners, a backend's other interfaces |
backend.As in internal/backend/guard.go, because the registry's backends are behind its guard, whose type has only backend.Backend's methods, so a type assertion to backend.Forgetter or *lima.Lima on one is always false |
tests |
the structure test's owners, git |
internal/hostgit, which runs git without the repo's fsmonitor, hooks, filters or signing programs, over ssh only, without the environment's GIT_* variables, prompts, replace refs or grafts. It's also the only package whose string literals may be "push", whole (names), and none is: a --clone VM's copy goes through the backend's Exec (internal/vm/cloneseed.go), never git's transport, whose receive-pack refuses shallow and SHA-256 repos. Nor may any other package's be "diff-files", which enters each submodule, where that repo's own config can name a filter: hostgit.DiffFiles doesn't. In tests, which run plain git to make their repos, it's internal/stubtest's Git, which leaves out git's variables that pick a repo, its files or its config (GitEnv), so a git that runs the tests, such as a hook's or git rebase --exec's, never sends a test's git to the checkout itself |
nothing else |
forbidigo, os.UserHomeDir, and the structure test's owners, HOME |
paths.FromEnv in internal/paths/dirs.go, which reads HOME once into paths.Dirs.Home, so a test or an e2e run that sets its own HOME moves every path devvm takes from it |
tests |
the structure test's owners, DEVVM_ variables |
readOverrides in internal/cli/overrides.go, which reads a test build's stand-ins, while a release reads none |
the settings in envSettings, and tests |
the structure test's owners, shell quoting |
internal/shell, whose Quote and QuoteJoin quote words for a POSIX shell, so a value never runs as a command, and QuoteLine a word on one line for bash |
tests |
the structure test's owners, the VM-name grammar |
internal/vmname, whose IsVM tells a project VM's name from an image's, so gc never takes a project VM for an image |
tests |
the structure test's owners, VM names |
internal/vmname, whose VM is the name of every machine devvm runs on a backend: a project VM, an image's machine, a build VM, or a VM's old machine while a remake makes the new one. A name is made a VM only where it's read: Parse takes a project VM's name from an argument or a file name, and also reads vm.json's name and runs in project.Nth, ParseListed one a backend lists, VM.UnmarshalText one in a JSON file (one path element that doesn't start with -, or none, and any machine's, so a field that must hold a project VM's is still checked with IsProject), Image names an image's machine and VM.Aside a remake's old one, and a backend's build VMs are typed constants. A struct field, a parameter or a result named for a VM (vm, vms, otherVM, vmName) whose type is a string, a pointer to one, a list of them or a map keyed on them fails, and so do a conversion of anything but a literal to vmname.VM and a type alias of it, so a path, an alias or a folder's name is never passed for a VM's name. The check goes by names, so it doesn't see a VM's name in a string named otherwise (target, client, parent, to, name), vmname imported with a dot or reached through a type parameter, or a VM joined to a string constant, whose type is still vmname.VM (l.VM+lineNoLinks in internal/vmssh/links.go) |
msg.M.VM in internal/msg/msg.go, which reads back the VM a message's function took; internal/stubtest, whose stubs stand in for limactl and ssh, whose arguments are strings; the names notNames lists that aren't a VM's, such as backend.Registry.NewVMs, a backend's name; and tests |
the structure test's owners, hosts |
internal/proxy/host.go, whose NormHost reads a host as the proxy judges it, the one form every judge of a host compares: a host of printable ASCII lowercased, in ASCII alone, and its one trailing dot dropped, and any other host left as it is, which HostOK refuses, so no Unicode fold makes another name match. An address is bare, or an IPv6 address in one pair of brackets, never one with a stray bracket. Its Host is what a matcher takes, such as a rule's matchHost and NO_PROXY's. A call to package strings that drops a dot (Trim, TrimLeft or TrimRight with a cutset that holds ., TrimSuffix or CutSuffix with "."), or that folds or trims an argument named for a host (ToLower, ToUpper, EqualFold, TrimFunc, TrimLeftFunc or TrimRightFunc of host, sni or u.Hostname()), fails, and so does a conversion to proxy.Host of anything but a literal. The check goes by names and calls, so it doesn't see a host's case folded in a variable named otherwise, a dot dropped by slicing, or a host mapped rune by rune (strings.Map) |
the functions free lists by file and name, each with why: trimDots in internal/proxy/request.go, which drops a path's segments' trailing dots; urlHost in internal/vm/cloneseed.go, which reads a remote's ssh host as ssh does, to find a VM's alias, its case folded and its trailing dot kept; safeIndexPath in internal/vm/cloneworktree.go, which drops a path segment's trailing dots and spaces as Windows does; and machines.fillPassword in internal/backend/lima/start.go and transportHelper in internal/vm/cloneconfig.go, which check that a string has only the characters of a set that holds .; and tests |
the structure test's owners, the coding agents |
internal/agents, whose Defs hold every fact devvm keeps of each agent, so no copy of an agent's list or paths goes stale when one is added. A string literal that is an agent's name or a login file's kind, whole, or that holds an agent's folder below the home folder, fails, and code of one agent's own names the agent by its constant there. Comparing with that constant, or with one named after it such as secrets.ClaudeToken, a case for it, looking for it with slices.Contains or slices.Index, looking it up in a map, a map literal keyed on it and strings.HasPrefix, HasSuffix, EqualFold or Contains with it fail too, outside the files named for the agent, such as claude.go, so the rest of devvm asks the agent's Def and a new agent changes none of it. A list that holds every agent's name, tests included, fails as a copy of agents.Names(), and so does a CLI test script's line that lists agents as a message does, for which the runner gives $AGENT_CHOICES, $LOGIN_AGENTS and $KEY_AGENTS (adding a coding agent) |
internal/stubtest, whose stubs are named after the commands they stand in for, and tests; for a name, the value of a constant that devvmNameFree lists with its reason and the only files that may use it: vm.CursorCommand, the Cursor editor's cursor command, which devvm cursor runs and isn't the agent's, used in internal/vm/ssh.go and internal/cli/cursor.go alone and compared with as an agent's constant is; for the comparisons, the files whose names hold the agent's name as a word, and the constants devvmSwitchFree lists in one file each with its reason: the claude secret's own checks, which are a secret's, and Codex's binding name in logins.go |
the structure test's owners, the toolchains |
internal/image, whose SharedTools holds every fact devvm keeps of each toolchain: its members, the files that call for it, its installer, its guest environment, its PATH folders and its version files. A string literal that is a toolchain's name or a member's, whole, fails, so code elsewhere asks the table, and a new toolchain is an entry there (adding a toolchain) |
internal/stubtest, and tests |
the structure test's owners, image names |
internal/image, whose Name is an image's name and splits it into its layers (Layers, Parent, Has), whose NameOf joins layers into one, and whose ParseName reads the name the user gives, which build.Names' Parse checks against the layers there are. devvm build, devvm rebuild and devvm images rm read their names there once, and the rest of devvm passes the image.Name on |
tests |
the structure test's owners, state.ReadHash and project.Parents |
the finder in internal/vm/finder.go, whose target finds the VM every command acts on: the folder's own, the nearest parent folder's under --here and --parent (resolveFolder), or one named (devvm rm VM). It finds a folder's VM by the state that records the folder (finder.state, by the path's hash first, then recorded), offers to move a VM whose folder moved there (moveHere in internal/vm/move.go, the match here.movedFrom), and names a new VM by the first of the folder's names whose VM folder is free (newName, project.Nth). Its need says what the command needs of the VM, and need.check is the one place that refuses one that isn't there, one made for an earlier folder at its path, one whose remake didn't finish and one whose creation didn't, the last with refuseUnfinished, which every start (starter.bringUp in internal/vm/start.go) makes too. It reads the folder devvm runs in only then, so the commands that act on no folder's VM run in a folder that's gone. The VM it finds is a target (internal/vm/target.go). It holds what the VM's backend told the finder, which each start and stop of the VM then updates, and it runs what a command does with that VM: exec, shell, stop, running, ownSSH and the name of its ssh config entry |
internal/state, and tests |
the structure test's owners, hostsafety.Walk |
the start in internal/vm/start.go, whose starter.walk walks a VM's project folder once for each check of the folder on the host, for the git repos nested in it, which .git protection goes by (gitprotect.Protector.Nested), and on Linux hosts its set-id files, so a check never walks the folder twice. It walks when a VM is made and when a check finds it stopped, at a launch or at devvm stop (starter.hostChecks), and at devvm git-protect on a stopped VM, never at a launch into a running VM |
internal/hostsafety, and tests |
the structure test's owners, state.ReadAll |
the inventory in internal/vm/inventory.go, which reads every VM's state (ReadStates), and with ReadInventory the backends' lists too, each within its wait, for every listing of VMs: devvm ls, devvm space, devvm images and devvm gc, the ssh config, devvm gc --orphans, the links, devvm secret's list, finding a VM by its name and the mounts that devvm's SSH agent checks a key against. Its one failure policy is that a backend that can't list fails a listing (Inventory.Err) only when some VM's state names it, and that a state that can't be read is a row of its own, which the readers leave out and ToolsInUse and Mounts fail on. state.VMNames, which fails on such a state, stays for the readers below internal/vm: netpolicy, ports and sshconfig.ChooseAlias |
internal/state, and tests |
the structure test's owners, paths.Dirs.AgentSettings and paths.Dirs.AgentLogins |
devvm's agent store: agentStore in internal/vm/agents.go for the agents' settings, which the mounts, the setup's copies, a remake's home and devvm agent import take, and secrets.LoginFile in internal/secrets/secrets.go for their logins, which the setup's copies and the proxy read, so nothing reads an agent's files from the home folder but vm.AgentImport |
internal/paths, and tests |
the structure test's owners, paths in devvm's folders |
internal/paths, whose Dirs and VM name every file and folder devvm keeps, so the layout, its golden listing in testdata/script/layout.txtar and a VM's teardown miss none. A filepath.Join onto a Data or Config field fails, and so does an os.MkdirTemp or os.CreateTemp there whose name is a literal; a name from paths, such as paths.ToolsBuildPrefix, passes |
tests |
forbidigo matches only the function a call names, so the checks that look at a call's arguments are in the structure test. It finds a host command in an exec.Command or exec.CommandContext call that names it, as a literal or as a constant, whatever name the file imports os/exec under. It finds a DEVVM_ variable in a call to any function or field named Getenv or LookupEnv, in any case, so t.Getenv and a getenv parameter count as well as os.Getenv, and it finds HOME the same way. The settings envSettings lists are the ones users set, DEVVM_NO_TOOL_CHECK, DEVVM_NO_RELEASE_CHECK, DEVVM_LIMA_HOME, DEVVM_SECRET_SERVICE and DEVVM_FROM; names mode, DEVVM_MESSAGES, which any build has; and the variables devvm sets for its own processes, DEVVM_GUESTFWD for devvm _qemu and DEVVM_DAEMON_STATUS for each background process internal/daemon starts.
The structure test also finds a copy of an owner's code by its text, in literals. A string literal outside tests that holds '\'', the escaped quote a shell quoter writes, belongs in internal/shell, and one that holds [0-9a-f]{14}, the hash at the end of a project VM's name, belongs in internal/vmname. A quote written as a rune, such as '\'' in Go, isn't a string literal, so it doesn't count. One that holds a coding agent's folder below the home folder, such as .codex/ or .pi/agent, belongs in internal/agents, and so does one that is an agent's name or a login file's kind, whole, such as "opencode" (names), so code of one agent's own names it by its constant there, such as agents.Opencode, and a longer text that mentions an agent, such as a command's example, doesn't count. A literal that is a toolchain's name or one of its members', whole, such as "dotnet" or "pnpm", belongs in internal/image in the same way, so code elsewhere finds a toolchain's facts in its image.SharedTools entry. A literal that is "push", whole, belongs only in internal/hostgit, which holds none, so no package passes push to git: a --clone VM's copy goes through the backend's Exec instead (internal/vm/cloneseed.go, the copy into a clone VM), because git's receive-pack refuses shallow and SHA-256 repos, and a second transport would drift. A literal that is "diff-files", whole, belongs only in internal/hostgit too, whose DiffFiles adds --ignore-submodules=all, because git diff-files otherwise runs git status in each submodule or embedded repo, where that repo's own config can name a filter that devvm's git doesn't turn off. In the same way, separators finds a copy of a parser by what it splits on: a call to any function of package strings with + as an argument, as a literal or as a constant, splits or joins an image's layers, so it belongs in internal/image. A call with another argument that holds a +, such as strings.ContainsAny(arg, "+,"), doesn't count.
The shared tools have one owner too, the table image.SharedTools in internal/image/tool.go, whose agents' entries it makes from the coding agents' registry, agents.Defs (adding a coding agent). Each entry, an image.ToolDef, holds a tool's name, its kind (a toolchain or an agent), its members (the tools in the lock that its name stands for, such as pnpm and bun for node), the files in a project folder that call for it, and its installer, which is mise for every tool but rust, which rustup installs, and dotnet, which assets/shared-tools/build.sh unpacks from Microsoft's SDK archive. A toolchain's entry also holds the environment that every VM's shells get for it, such as NPM_CONFIG_PREFIX and .NET's telemetry switch (Env), the folders of the VM's home that go on every VM's PATH, where its global installs go (PathDirs), and the members whose version files mise reads in a project (VersionFiles). mise locks dotnet's version without a download, because its own installer runs Microsoft's install script, which checks nothing, so devvm adds each platform's archive and its SHA-512 from Microsoft's release metadata to the lock (withSDKDownloads in internal/tools/dotnet.go), and Share.Build passes them to build.sh (image.OwnDownload), which checks the archive with devvm-fetch. image.Toolchains, image.Agents, image.GroupTools, the files that make devvm choose a toolchain for a new VM, the lock's check for downloads (image.NoDownload) and the devcontainer.json features that devvm maps to a toolchain all come from it. So do the files that every launch's setup writes for the toolchains: /etc/devvm/toolchains.sh, with every toolchain's environment and PATH folders (image.GuestEnv and image.GuestPath), which base's /etc/profile.d/devvm-tools.sh reads in every shell, as it reads the agents' /etc/devvm/agents.sh, and the VM's mise setting that names the tools whose version files it reads (image.VersionFileTools). The image builds read none of them, so a toolchain's environment changes no image. The structure test fails on a string literal outside internal/image that is a toolchain's name or a member's, whole, so code elsewhere asks the table, through image.Def, an entry's Installer or its other fields, rather than naming a toolchain. Adding a toolchain and adding a coding agent list the files a new shared tool needs, and the agreement tests fail until the table and those files match.
The scripts that devvm's builds run with bash have one owner for the machine they run on, assets/prelude.sh, whose $devvm_arch, $devvm_libc and devvm_sha give each script its architecture, its C library and its pinned checksum for each download (the scripts' prelude). A script reads them rather than run uname -m or look for apk itself, and checks that the prelude came first with : "${devvm_arch:?}" for each variable it reads, which also tells shellcheck that the variable is set. Go reads each of those scripts through image.OwnScript, which puts the prelude before it, so a recipe, a tool image's key and the conversion's copy of oci/build.sh all hold the two together. TestPreludeUsers in internal/image fails when a script that doesn't get the prelude, such as assets/oci/bootify.sh or assets/guest/'s, uses it, or when a script reads a variable without that check. testdata/script/prelude.txtar checks which pin devvm_sha picks from each script's pins on arm64 and amd64, with glibc and with musl. A CLI test or a Go test that sources one of these scripts sources assets/prelude.sh first.
internal/paths also owns how a path on the host is resolved and compared with a folder, in resolve.go, whose comment says which resolver each question takes. paths.Physical resolves every symlink as far as the path exists, for where a folder or file really is, such as a project folder against devvm's own folders or an SSH key against the folders VMs mount. paths.PhysicalParent resolves only the folder's symlinks and keeps the last element as named, for a path that may itself be a symlink devvm mustn't follow, such as a key's recorded path or a Seatbelt rule. filepath.EvalSymlinks itself, which fails when the path doesn't exist, is for a path that must exist, such as the folder devvm runs in. Then paths.Within tells whether a path is a folder or inside it, and paths.Below whether it's inside it only. Both compare names, so both paths are resolved the same way first.
A VM's state, vm.json, has one owner too, internal/state, which reads and writes the whole file and knows only its core fields. Every other package that keeps something of a VM's owns one section of it, with its own type, its name (Section), and an Of that reads it through state.Section: internal/netpolicy owns net, internal/gitprotect git, internal/ports ports, internal/sshagent agent, internal/tools tools, internal/secrets secrets, and internal/vm size, clone, devcontainer, desktop and links (internal/vm/state.go). A section's type keeps what the user asked for at its top level and what devvm made under made. A change goes through state.VM.Update, which takes the VM's lock, reads the file again, runs the change and writes the file once: the change sets its section with state.SetSection and works out a list's new value from the file as it is then, never from what the command read earlier, so a change another devvm made meanwhile is kept. A change that fails writes nothing. Update holds one VM's lock, so a change takes no other lock inside it, and a change to several VMs updates each in turn. Test builds and the tests panic on a lock taken out of that order (the lock rule). state.VM.Claim is Update that also holds the claims lock, for what no two VMs may have (ports.Allocator chooses every VM's host port through it), and state.VM.Create writes a new VM's whole state once, its ssh alias chosen under the claims lock. A build VM has no state, so ports.Allocator.Build chooses its ssh port through state.Claims, which holds the claims lock alone. A VM's alias is one vmname.IsAlias accepts, or devvm doesn't use it. internal/vm's checkState reads every section of the folder's VM's state as the VM is found, so a section that can't be read stops the command instead of reading as empty. A new section adds its check there.
When two places must agree but can't be one, a test checks that they agree. TestEveryPartHasAPolicy checks that every image part has its policy, TestSharedToolsPolicies that the policies in assets/shared-tools/ are one for each shared tool in image.SharedTools, TestConfigTools that assets/shared-tools/mise.toml lists each shared tool's members and nothing else, TestBuiltinPolicies that every policy devvm ships parses, TestEveryMessageIsUsed that every message has a caller, TestDocLinks that every doc link is a message and a heading, TestPreludeUsers that only the scripts that get the prelude use it, TestDefsComplete that every coding agent has its [tool_alias] line and its row in the docs' Supported agents table, TestProvidersComplete that every provider in agents.Providers has its row in the docs' table of the API keys the proxy puts in, TestToolchainsComplete that every toolchain has files that call for it and its row and section on the toolchains page, which names those files and its PATH folders, TestFormatsCoverLogins that every agent's login file has its format in internal/agentlogin, TestBumpCoversPins that scripts/bump.sh moves every pin it finds, or says why it's left (updating pinned versions), and TestReferenceIsCurrent that the CLI reference matches the commands. A new pair of places that must agree gets such a test.
A review of a body of work, and the review before a release, look across the code for copies:
- two parsers of one format
- a path built outside
internal/paths - a list of files kept beside the folder that holds them
- a value encoded in a string
- two messages that say one thing
- a comment that says to keep two places in sync
- a test that copies a constant
Each copy gets one of three outcomes: extend the owner, make one owner, or leave it. Leave it when the only shared helper would be the wrong one, because a copy costs less than the wrong helper, and wait for a third copy before making one. The pass is part of those reviews, not a step every change runs.
A value that lets whoever holds it act as you or as a VM is a redact.Secret, from the moment devvm reads it until the place it's used. That covers a VM's proxy password (netpolicy.Key, proxy.Config.Password, backend.Confinement.ProxyPassword) and a build proxy's, a secret's value (secrets.Store.Value, Get and Save, and what ui.UI.Secret reads), the company proxy's password and the Proxy-Authorization the proxy sends it, the values the proxy caches for a VM's bindings (proxy.Lookup), and an agent's API keys and tokens once they leave its login file (agentlogin.File.Get and SetKey, and the tokens a capture or a refresh brings). Two such values stay strings, as where secret values live explains: the value on its way through platform.KeychainGet and KeychainSet, which secrets.Store makes a Secret at once, and devvm desktop's VNC password, which you must see. A Secret prints as <redacted> with %v, %s, %q, %x, %#v and every other verb, so a log line, an error or a struct printed with %+v never shows it. Its value is behind a pointer, because fmt prints a value in an unexported field without calling its Format, and such a field then shows only an address. Two Secrets are equal with == only when they're the same one, so compare their values with Reveal, or the structs that hold them with reflect.DeepEqual.
Reveal is the only way to the value, and forbidigo refuses every call to it but in tests, so each place that must use a value says why in a //nolint:forbidigo // <why> on that line: the proxy's password check and the headers it puts values in, the store's file and the Keychain, the VM's proxy URL and a login's file, its refresh and its claims. Anywhere else, pass the Secret on. testdata/lint/forbidigo.go keeps a call to Reveal that the rule must report. The structure test refuses a struct that embeds redact.Secret outside internal/redact, which would take on its methods, and an interface that declares Reveal() string, which would carry a value past forbidigo's eye. It reads the source alone, so it doesn't see a Secret embedded through another type or reached through reflection.
Encoding a Secret as JSON or as text is an error (redact.ErrEncode), never <redacted>, so a value written somewhere by accident fails at once rather than losing your login. A file that must hold the real value therefore writes it through its own wire type, a struct with the value as a string that only that file's reader and writer use:
- The proxy's config,
proxy.json, isconfigFile, withConfig's fields inConfig's order, so its bytes, and theSumthat decides whether a running VM's proxy starts again, are the same as before.TestConfigFileholds the two types together. - A VM's key in
vm.jsonisnetpolicy.NetMade's ownMarshalJSONandUnmarshalJSON, throughnetMade. - A secret's file without a Keychain is the value and a line's end, which
secrets.Store.savewrites andsavedreads. - A login's file is the agent's own format, read and written whole as a map so that fields devvm doesn't know stay, and a key or token leaves the map through
agentlogin'stokenand goes into it throughsetToken.
To add a field that holds a secret, give it the type redact.Secret. If a struct with it is written to a file, add the field to that file's wire type, and check that a frozen release's files still read and write the same bytes: TestV010ProxyConfigs does it for proxy.json, TestFixtureVMStates for vm.json's sections, TestFixtureStoreGet for a secret's file on Linux, and TestFixtureAgentStore for the agents' login files, which every read leaves as they were.
State files describes the layout, and the design note says why it's built that way. Every path in it comes from internal/paths. paths.Dirs names the shared folders and files, and Dirs.VM(name) gives a VM's paths.VM, whose methods name each file in the VM's folder: Dirs.VMDir(hash), vms/<hash>/, for a project VM, and run/builds/<name>/ for a build VM. A new file of a VM's gets a method on paths.VM, so it lands in the VM's folder, and vmFolders.teardown in internal/vm/teardown.go deletes it with the folder, with no list of files to update. A new socket goes in Dirs.Run(), named by a hash, and TestSocketsFit checks the longest path against paths.SocketMax. A new record that only devvm writes is JSON, read with encoding/json, which ignores fields it doesn't know, and written whole with state.WriteFile. A new default goes in internal/settings, which reads config.toml strictly and saves settings.json, and a new lock is an OS file lock (platform.LockFile and its kin) on a file that paths names.
The data folder and the config folder each hold a version file with their layout version, state.Layout in internal/state/layout.go. Before each command that reads them, state.CheckLayout takes version.lock in the data folder and compares both files with state.Layout. A folder without the file gets this devvm's version, the same version goes on, and a newer one stops the command with layout_newer, because a newer devvm changed the folders. An older one runs the migrations from that version to this one, in order, and then writes state.Layout into both files. skipsLayout in internal/cli/root.go lists the commands that skip the check: help, completion, the version and devvm's own hidden commands.
testdata/script/layout.txtar makes two VMs on the allowlist tier, a forwarded port, a link and a secret, lists every file and folder under the data and config folders, and compares the lists with the ones at the end of the script, one for macOS and one for Linux. A change to the layout, such as a new file, a renamed folder or a file that moves, changes a listing, so the test fails until you update it. When it does, decide whether the change needs a new layout version:
- A change that an older devvm would read wrongly, or a file that moves, raises
state.Layoutby one. - It adds a
state.Migrationat the end ofmigrations(), which changes the folders from the version before to the new one. A migration takespaths.Dirs, and a run that it fails stops before the versions change, so the next run tries it again.TestMigrationschecks that there's one migration for each version before this one, andTestCheckLayoutruns fake ones. - It updates the listings in
layout.txtar.
A new file that an older devvm doesn't need to know about, or a field added to a JSON file, which an older devvm ignores, keeps the version and changes only the listings.
Someone who upgrades devvm keeps their VMs, defaults, agent store and secrets as the release they came from left them. Until 1.0, an upgrade from every release since 0.1.0 has to work. Each final release that changed what devvm writes on disk has a frozen copy of the state it left, called its fixture, and the tests run today's devvm on every fixture, so a change that breaks an older release's state fails the gate.
A release's fixture is the folder testdata/v<release>/. Its darwin/ folder holds the state that the release left on a Mac, and its linux/ folder the state it left on Linux. For 0.1.0, that's four VMs' states, its defaults, its agent store and logins, the stubs' record of the VMs, and what its --json printed for them, and the folder's README.md lists what each VM has. The release made these files itself. Its generate.sh checks out the release's tag in a temporary folder and runs generate.txtar with that version's own CLI test harness, then copies what the run left, with each file's mode in modes, because git doesn't keep modes.
A fixture is frozen. It's generated once, from the release's own binary, and never edited or generated again, so never run its generate.sh from a newer devvm and never change its files. A release whose state is the same as the one before it adds no fixture, and neither does a release candidate, such as 0.1.1-rc.1, because only a final release that changes the state gets one.
The unit tests read every fixture's files with today's readers. stateFixtures in internal/vm/fixture_test.go lists each release's expectations: its VMs, the version of their vm.json, its layout version, its clones of one repo, and functions that check its VMs, its defaults and its agent store. 0.1.0's entry is v010Fixture in fixture_v010_test.go. TestFixtureVMStates, TestFixtureVMsRead, TestFixtureSettings, TestFixtureAgentStore and TestFixtureClonesReadAsOneRepo run once for each release and system, and they check that each field the release wrote reads and writes back unchanged. TestStateFixturesListed fails when a folder in testdata has no entry, or an entry has no folder. Two packages keep a table of their own for what only they read. In internal/proxy, fixtureBinaries records the SHA-256 of the binary that made each release's state, which its proxy configs name, and TestFixtureBindings and TestFixtureProxyConfig read every release's bindings files and proxy configs. In internal/secrets, storeFixtures names a secret that each release's store on Linux keeps as a file, which TestFixtureStoreGet reads through a VM's binding. TestV010Rules is a copy of 0.1.0's own tests of the proxy's rules, kept apart from today's.
The CLI tests run today's commands on each fixture. A release's scripts are in testdata/script/, named fixture_v and the release's version without its dots, such as fixture_v010.txtar, fixture_v010_clone.txtar and fixture_v010_network.txtar for 0.1.0. Each one puts the state into a sandbox with fixture v<release>, which moves it to the sandbox's folder: the folder's path, each VM's name hash, its folder's and .git's identities and its backend's place become what they are there, each host port, and each port that a VM or the defaults forward, becomes one of the sandbox's own that nothing on this host listens on, and nothing else changes. The ports change because a launch that finds a VM's port taken, by a program of yours or by another run of the tests, rightly chooses another one and edits the VM's Lima config, and warns that it can't forward a port a program has, such as a web server of yours on 3000. A script names a forwarded port by what it was, as $FIXTURE_PORT_3000. The script then runs today's devvm on it. Each --json must have everything the release's had (json_superset), the read-only commands must change no file, and a launch must start each VM as it is, without a Lima edit. The scripts stay separate for each release, because their checks name that release's VMs and what each one has, and TestFixtureScripts in internal/cli fails when a fixture has no script or a script names a fixture that isn't there.
A change that reads or writes state, such as a new command, a new section in vm.json or a new field in a record, runs its new commands on every fixture in the same commit, and reading the files isn't enough. Add the steps to each release's scripts, as fixture_v010_network.txtar runs rules by method and path on 0.1.0's app VM and fixture_v010_clone.txtar runs devvm clone add on its web VM. When a fixture's test fails, today's devvm breaks the state that the release's users have. Fix devvm, or add a migration, but never change the fixture.
A change in what devvm does with existing state gets an entry marked Breaking in CHANGELOG.md, in the Unreleased section at the bottom until its release moves it to the top. When the user has to do something about it, such as run a command, devvm also tells them once, at the first launch after the upgrade.
At release time, after the tag exists, a final release that changed the state format gets its fixture. A release candidate gets none, even when it changed the state, and its final release's fixture holds that state:
- Copy the newest fixture's
generate.sh,generate.txtarandREADME.mdintotestdata/v<release>/. Set the tag, the version and the script's name ingenerate.sh, and add the VMs and commands togenerate.txtarthat make the state the release added. - Run
generate.shon a Mac and on Linux, which writesdarwin/andlinux/. 0.1.0's were made on an arm64 Mac and on x86_64 Fedora. - Add the release's entries in
stateFixtures,fixtureBinariesandstoreFixtures, and its scripts, made from the newest release's scripts with checks of its own VMs. - Commit the folder as the run left it. The older fixtures stay as they are.
An upgrade from every release since 0.1.0 works until 1.0. When a release leaves the window, its fixture and the code that only its state needs, such as a reader of a field that only that release wrote, go together, in one commit that says which release left and why. The commit deletes testdata/v<release>/, its scripts and its entries in the tables above.