Documentation
¶
Overview ¶
Package fleet holds the machines registry: the one file that says what each machine in the fleet IS, and therefore what may be placed on it.
THE LOCK (Glenn, 2026-09-18): runner hosts are CI-only. No card, no probe and no load may be placed on a machine that serves the merge group's shards. A card and a CI shard on one host make the shard slow, the gate red and the queue stop -- this was measured all through 2026-09-17, when the merge group's darwin legs starved behind the coordination bench's own children and nothing landed for twenty minutes at a time.
The registry exists because a bench name reached a machine as a bare string: `--bench batman` was a hostname the fill loop would happily ssh to, and nothing in the tools knew that batman is six CI runners and not a card bench. Now a bench name is RESOLVED -- every verb that puts work on a machine asks the registry first, and a name whose roles lack `bench` is refused by name, with the reason and the remedy on the line.
The file is data, tab separated, kept in git beside the lanes file:
name<TAB>ssh<TAB>os/arch<TAB>roles<TAB>seat<TAB>cores<TAB>notes
It is read WHOLE and validated whole: a partially-read registry is worse than none, because the half that read is the half that lets a card through.
Index ¶
- Constants
- type Machine
- type Refusal
- type Registry
- func (r *Registry) BenchNames() []string
- func (r *Registry) CertifiedBenchNames() []string
- func (r *Registry) Lookup(name string) (Machine, bool)
- func (r *Registry) Machines() []Machine
- func (r *Registry) Path() string
- func (r *Registry) RequireBench(name string) error
- func (r *Registry) WithRole(role string) []Machine
Constants ¶
const ( // RoleBench says cards, probes and load may be placed here. It is the only role that // permits work, and every other role is silent about work. RoleBench = "bench" // RoleRunner says the machine serves the merge group's CI shards. RoleRunner = "runner" // RoleCoordination says a friend's own window lives here. RoleCoordination = "coordination" // RoleServices says the stack lives here: Loki, Grafana, Redis. RoleServices = "services" )
The roles a machine may carry. They are a SET, not a rank: a machine is every one of the things its line says it is.
const ( ReasonRunnerHost = "runner-host" // it serves the merge group's shards ReasonCoordinationHost = "coordination-host" // a friend's window lives there ReasonServicesHost = "services-host" // the stack lives there and nothing else may ReasonNotABench = "not-a-bench" // it carries no role that permits work ReasonUnknown = "unknown-machine" // the registry does not carry the name )
The reasons a machine may not take work. They are tokens, not prose, so a loop reading the line can branch on one and a person reading it learns the same thing.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Machine ¶
type Machine struct {
Name string // the bench name every verb's --bench takes
SSH string // the ssh target; an alias in ~/.ssh/config or a host
OS string // linux, darwin, windows
Arch string // x64, amd64, arm64
Roles []string // sorted, unique, every one from knownRoles
Seat string // the nova-secrets seat on the machine; "" when it carries none
Cores int // whole cores, as the machine counts them
Notes string // free text; "" when the line said `-`
Line int // the line of the file this came from, for a refusal that can be found
}
Machine is one line of the registry.
func (Machine) AllowShared ¶
AllowShared reads the dated exception out of the notes: `allow-shared=<YYYY-MM-DD> <why>`. It returns the date, the reason and whether one is there at all.
func (Machine) Certified ¶
Certified reads the certification out of the notes: `certified=<YYYY-MM-DD>`, with anything after the date free text (the report it was written from, usually). It answers the date and whether the machine carries one at all.
type Refusal ¶
Refusal is what a verb prints when a machine may not take the work it was handed. It carries the machine, the reason as a token, and the remedy written the way it would be typed.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is the whole machines file, read and validated.
func ReadRegistry ¶
ReadRegistry reads and validates the machines file whole. Every refusal names the file, the line and what the line should have said; nothing is guessed and nothing is skipped, because the half of a registry that reads is the half that lets a card through.
func (*Registry) BenchNames ¶
BenchNames is every name a verb may put work on, in file order.
func (*Registry) CertifiedBenchNames ¶
CertifiedBenchNames is THE POOL: every machine that may take work AND has been certified, in file order. It is what a verb fills when the caller names no bench, so a bench joins the fleet's work by its registry row and by nothing else -- no list in any Go file, no edit to any tool, no release.
func (*Registry) RequireBench ¶
RequireBench is THE guard. It answers nil when the named machine may take work, and a *Refusal naming the reason and the remedy when it may not -- an unknown name, a CI runner host, the coordination bench, a services host.
Every verb that reaches a machine calls this before it reaches one. The check is on the NAME, before any ssh, so a refused machine is never even connected to.
Source Files