Files
mesh-delivery/modules/mesh-delivery-sdk/buildstep/toolchains.go
T
jschoubben a66583236a A-471: a toolchain is agreed, reported and named by its language version alone
A build node whose installed patch differs from the ask's takes the ask: one shared
comparison in mesh-delivery-sdk buildstep (LanguageVersion, SameToolchainVersion),
used by the agreement (indexer, builder, checker), a build node's step guard and ask
check, and the builder's digest list. A fingerprint names the language version, so
every module's fingerprint changes once.

Builds: design 47 G A-471 (G-22-lead-answers-2.md)
2026-11-17 15:53:05 +01:00

121 lines
4.7 KiB
Go

package buildstep
import (
"fmt"
"sort"
"strings"
)
// **The toolchain a language's builders agree on** (novox/hq ADR 0584): the nodes report their toolchain in the state
// `toolchains` of a node-build seat (the seat's generated type holds the entry); this file holds the one rule over the
// entries every reader of that state shares, over a seat-neutral form, so no reader copies it.
// ToolchainNoReport is the reason AgreedToolchain gives when no node has reported a language's toolchain.
const ToolchainNoReport = "toolchain not yet reported"
// LanguageVersion is the version of a language a toolchain is agreed, reported and named by (design 47 G, A-471): its
// major.minor, so "go1.27.4-X:nodwarf5" and "go1.27.3" are "go1.27" and "v26.13.1" is "v26.13". A text before the first
// digit (go, v) is kept. A version with no major.minor is returned as it is.
func LanguageVersion(version string) string {
start := strings.IndexAny(version, "0123456789")
if start < 0 {
return version
}
end, dots := start, 0
for end < len(version) {
c := version[end]
if c >= '0' && c <= '9' {
end++
} else if c == '.' && dots == 0 && end+1 < len(version) && version[end+1] >= '0' && version[end+1] <= '9' {
dots++
end++
} else {
break
}
}
if dots == 0 {
return version
}
return version[:end]
}
// SameToolchainVersion is whether two installed versions are one language version (LanguageVersion).
func SameToolchainVersion(a, b string) bool { return LanguageVersion(a) == LanguageVersion(b) }
// NodeToolchain is one node's entry of a language, as read from a build seat's state toolchains (the entry is Toolchain).
type NodeToolchain struct {
Node string
Toolchain
}
// SittingOut is a node whose toolchain of a language is not the agreed one: it builds nothing of that language until
// it reports the agreed version (novox/hq ADR 0584 clause 2).
type SittingOut struct {
Node string
Version string
Recipe string
}
// Agreement is what the nodes' entries of one language come to. Toolchain is the agreed one (its language, version and
// recipe), set when Wait is empty.
// Wait is why nothing is agreed: "toolchain not yet reported" with no entries, or "builders disagree" naming each version
// and recipe with the nodes reporting it, when no version has a strict majority. SittingOut lists, sorted by node, the
// nodes that report another version than the agreed one.
type Agreement struct {
Toolchain Toolchain
SittingOut []SittingOut
Wait string
}
// ToolchainAgreement is the agreed toolchain of a language: the language version (LanguageVersion: the patch is not counted, A-471) and recipe a strict majority of the reporting
// nodes report (novox/hq ADR 0584 clause 1). With no strict majority (two against two) or no entry it gives no toolchain
// and says why in Wait. The answer does not depend on the entries' order. The entries must all be of one language.
func ToolchainAgreement(entries []NodeToolchain) Agreement {
if len(entries) == 0 {
return Agreement{Wait: ToolchainNoReport}
}
type identity struct{ Language, Version, Recipe string }
groups := map[identity][]string{}
for _, e := range entries {
k := identity{e.Language, LanguageVersion(e.Version), e.Recipe}
groups[k] = append(groups[k], e.Node)
}
for k, nodes := range groups {
if 2*len(nodes) > len(entries) {
a := Agreement{Toolchain: Toolchain{Language: k.Language, Version: k.Version, Recipe: k.Recipe}}
for _, e := range entries {
if LanguageVersion(e.Version) != k.Version || e.Recipe != k.Recipe {
a.SittingOut = append(a.SittingOut, SittingOut{Node: e.Node, Version: LanguageVersion(e.Version), Recipe: e.Recipe})
}
}
sort.Slice(a.SittingOut, func(i, j int) bool { return a.SittingOut[i].Node < a.SittingOut[j].Node })
return a
}
}
parts := make([]string, 0, len(groups))
for k, nodes := range groups {
sort.Strings(nodes)
parts = append(parts, fmt.Sprintf("%s recipe %s on %s", k.Version, k.Recipe, strings.Join(nodes, ", ")))
}
sort.Strings(parts)
return Agreement{Wait: "builders disagree: " + strings.Join(parts, "; ")}
}
// AgreedToolchain is ToolchainAgreement's toolchain, or none and why (its Wait).
func AgreedToolchain(entries []NodeToolchain) (tc Toolchain, none string) {
a := ToolchainAgreement(entries)
return a.Toolchain, a.Wait
}
// ParseToolchainKey is the inverse of ToolchainKey.
func ParseToolchainKey(key string) (node, language string, err error) {
node, language, ok := strings.Cut(key, ".")
if !ok {
return "", "", fmt.Errorf("buildstep: %q is not a toolchain key, <node>.<language>", key)
}
if _, err := ToolchainKey(node, language); err != nil {
return "", "", fmt.Errorf("buildstep: %q is not a toolchain key: %w", key, err)
}
return node, language, nil
}