jschoubben
337126603e
The three shapes the substrate bootstrap needs and the host did not have. Until now tier 1 could not be raised at all -- step 0 is a package, step 1 a container, steps 2 and 3 actions -- so every line of the tier 1 and 2 designs was unbuildable. package -- present, never upgraded, never uninstalled. Removal is "forgotten", not "removed": the host cannot know what else needs the package, uninstalling a container runtime because a declaration changed would stop every container on the node, and the machine may have had it before the mesh saw it. Reporting it removed would claim an effect the host declined to have. container -- identified by a label carrying a digest of the declaration that made it. Comparing every field the runtime reports cannot be done reliably: a runtime normalises, defaults and reorders what it is given, and that is indistinguishable from real drift. There is no in-place update; a container's configuration is fixed at creation, so any change is a replacement, and saying so beats a partial update that leaves the running thing half-declared. This is the one shape the host removes, because it is the one the host created. action -- bundle-only, per ADR 0047. Verify is mandatory and does double duty: it is the idempotency check as well as the read-back. The host does not know what a database is, so "is it already there" is a question only the declaration can ask. `in` runs the action inside a named container, which steps 2 and 3 need. Parse now refuses actions; ParseTrusted permits them. The safe path is the default and the permissive one has to be named. The bundle and a local file handed to a root process use ParseTrusted; the link will use Parse. Also replaced the per-type "fields this type ignores" check with a field-set diff stated as what each type USES. The negative form needs every type revisited whenever a field is added, and the one nobody revisits silently accepts a field it will never read. Images must be pinned by digest (ADR 0046). A bundle naming a tag pins nothing. Verified against a real machine, not only fakes: an action ran and was idempotent on the second apply; an action that exits zero and satisfies nothing fails the apply; a real container was created, labelled, replaced when its declaration changed, exec'd into, and removed; a real package query round- tripped. Each new test was also confirmed to fail on an injected fault -- five injections, each breaking exactly its own test. One existing test changed: a vanished unit is now reported "forgotten" rather than "removed", which is what actually happened.
81 lines
3.1 KiB
Go
81 lines
3.1 KiB
Go
// Package bundle is the declaration the host carries.
|
|
//
|
|
// novox/hq ADR 0038: the host has one behaviour and two sources of declaration — the control
|
|
// plane when a mesh is reachable, and this when none is. The first node is not a different
|
|
// kind of node; it is a node whose mesh is not up yet, and this is what it applies until it is.
|
|
//
|
|
// Carried inside the binary rather than beside it, because "copy it onto a machine and run it
|
|
// is the whole installation" (ADR 0041) stops being true the moment a second file has to
|
|
// arrive with it.
|
|
package bundle
|
|
|
|
import (
|
|
_ "embed"
|
|
"errors"
|
|
"strings"
|
|
|
|
"github.com/novox/mesh-host/internal/declaration"
|
|
)
|
|
|
|
// substrate is the pinned tier-1 descriptor, appliable with no mesh present.
|
|
//
|
|
// A host built without one carries the placeholder below, and says so rather than applying
|
|
// nothing and reporting success — a host that silently did nothing on a first node would look
|
|
// exactly like one that worked.
|
|
//
|
|
//go:embed substrate.lock
|
|
var substrate []byte
|
|
|
|
// ErrEmpty means this host was built without a bundle.
|
|
var ErrEmpty = errors.New(
|
|
"this host carries no bundle. A host built without one cannot raise a first node, and " +
|
|
"applying nothing would look exactly like applying something")
|
|
|
|
// Raw returns the carried bytes, for inspection.
|
|
func Raw() []byte { return substrate }
|
|
|
|
// IsEmpty reports whether anything was built in. A bundle of only comments and whitespace is
|
|
// empty for this purpose: the placeholder is a comment, and treating it as content would mean
|
|
// a default build claims to carry a substrate.
|
|
func IsEmpty() bool {
|
|
for _, line := range strings.Split(string(substrate), "\n") {
|
|
line = strings.TrimSpace(line)
|
|
if line != "" && !strings.HasPrefix(line, "//") {
|
|
return false
|
|
}
|
|
}
|
|
return true
|
|
}
|
|
|
|
// Load parses the carried bundle.
|
|
//
|
|
// The same parser the link will use. A bundle that reaches a machine and is then refused by the
|
|
// host that carries it would be a build-time mistake discovered at the worst possible moment,
|
|
// which is why `mesh-host bundle` exists to ask before it matters.
|
|
func Load() (*declaration.Declaration, error) {
|
|
if IsEmpty() {
|
|
return nil, ErrEmpty
|
|
}
|
|
// ParseTrusted: the bundle arrives with the binary, so it may carry actions the link may
|
|
// not (novox/hq ADR 0047). The bootstrap needs them — creating the control plane's database
|
|
// happens before there is any mesh to ask for one.
|
|
return declaration.ParseTrusted(stripComments(substrate))
|
|
}
|
|
|
|
// stripComments removes whole-line `//` comments so a bundle can be annotated.
|
|
//
|
|
// It is JSON on the wire and a pinned, hand-authored artefact here, and a pinned thing nobody
|
|
// can annotate is a pinned thing nobody can review. Only whole lines: anything cleverer would
|
|
// need to know where strings begin and end, and a parser that half-understands its input is
|
|
// worse than one that does not try.
|
|
func stripComments(raw []byte) []byte {
|
|
var kept []string
|
|
for _, line := range strings.Split(string(raw), "\n") {
|
|
if strings.HasPrefix(strings.TrimSpace(line), "//") {
|
|
continue
|
|
}
|
|
kept = append(kept, line)
|
|
}
|
|
return []byte(strings.Join(kept, "\n"))
|
|
}
|