The running pre-G indexer publishes a repository's packages only when every package directory it published last is
still in the tree; G moved contracts/go and sdk to modules/, so mesh-delivery's packages, G's renamed paths among them,
are never published and nothing importing them builds (2026-11-13, indexer journal 'its packages are not published').
These are the trees of e70754ef, unchanged, without sdk/module.json (no second module). Nothing imports them; they go
once G's indexer runs and publishes without them.
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
327 lines
12 KiB
Go
327 lines
12 KiB
Go
// Package meshwantsclient is the client of the seat mesh-wants: the keys of its state wants, and the check and the codec
|
|
// of a want, a node's own want and a hold, which every module that reads or writes wants shares (the assigner that writes
|
|
// them, the node-engine, the provisioner and the artifact store that read them). The layouts are the seat's contract; this
|
|
// file writes the version and refuses what the earlier codec refused (novox/hq ADR 0528, ADR 0539, ADR 0546, ADR 0634 §4).
|
|
package meshwantsclient
|
|
|
|
import (
|
|
"encoding/json"
|
|
"fmt"
|
|
"regexp"
|
|
"strings"
|
|
|
|
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshwants"
|
|
"git.novox.be/novox/mesh-sdk/go/keys"
|
|
)
|
|
|
|
// The three values of the state wants, in the seat's types.
|
|
type (
|
|
// Want is a node's want for a module: the fingerprint it should run and the digest of the one composition it allows,
|
|
// or Removed, or Self when the node composes it itself; Newest and Rule name what holds the node back.
|
|
Want = seat.WantsByWantNodeModuleValue
|
|
// NodeWant is a node's own want: the digest of the node's own composition it may apply.
|
|
NodeWant = seat.WantsByWantNodeNodeValue
|
|
// Held is a fingerprint the assigner holds: the node whose health check failed on it, and the check's words.
|
|
Held = seat.WantsByHeldModuleFingerprintValue
|
|
)
|
|
|
|
// The rules of ADR 0429 §6 and ADR 0539 clause 6, by number, as a want or a difference names the one that holds a node back.
|
|
const (
|
|
RuleBuildDone = 1 // the build of F is done
|
|
RuleNotHeld = 2 // F is not held
|
|
RuleCanary = 3 // the node is the module's canary, or the canary runs F healthy
|
|
RuleStep = 4 // at most step other nodes are ahead (step 0: no limit, ADR 0528 §3)
|
|
RuleProviders = 5 // every provider the module requires runs healthy on that node, or at its canary
|
|
RuleGrant = 6 // the module's credential for F exists (grants.<module>.<fp>)
|
|
RuleComposed = 7 // the module's composition for that node at F exists (ADR 0539 §6)
|
|
// RuleProvisions: every provision the module requires on that node is provided (novox/hq ADR 0570 §4).
|
|
RuleProvisions = 8
|
|
)
|
|
|
|
// ruleRead is the highest rule a reader takes (novox/hq ADR 0614 §2, §4): 9 and 10 are kept for the verb wait and the
|
|
// capability hold of a later release.
|
|
const ruleRead = 10
|
|
|
|
// The answers a want carries to a failed backup before an apply (ADR 0539 clause 16).
|
|
const (
|
|
// BackupAgain is the answer to back the module up again before the apply.
|
|
BackupAgain = seat.WantsByWantNodeModuleValueBackupAgain
|
|
// BackupSkip is the answer to go on without a backup.
|
|
BackupSkip = seat.WantsByWantNodeModuleValueBackupSkip
|
|
)
|
|
|
|
// NodeWord is the last part of a node's own key.
|
|
const NodeWord = "node"
|
|
|
|
const (
|
|
wantWord = "want"
|
|
heldWord = "held"
|
|
srcWord = "src2:"
|
|
)
|
|
|
|
var (
|
|
moduleNameOK = regexp.MustCompile(`^[-/_a-zA-Z0-9]+(\.[-/_a-zA-Z0-9]+)*$`)
|
|
digestForm = regexp.MustCompile(`^sha256:[0-9a-f]{64}$`)
|
|
)
|
|
|
|
func moduleKeyPart(module string) (string, error) {
|
|
if module == "" {
|
|
return "", fmt.Errorf("wants: the module name is empty")
|
|
}
|
|
if !moduleNameOK.MatchString(module) {
|
|
return "", fmt.Errorf("wants: the module name %q holds a wildcard, whitespace, '=', an empty part between dots or a character a key refuses", module)
|
|
}
|
|
return keys.EscapeName(module), nil
|
|
}
|
|
|
|
func parseModuleKeyPart(part string) (string, error) {
|
|
if err := keys.CheckName("module", part); err != nil {
|
|
return "", err
|
|
}
|
|
module, err := keys.UnescapeName(part)
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
if back, err := moduleKeyPart(module); err != nil || back != part {
|
|
return "", fmt.Errorf("wants: the module part %q is not a module name as a key writes it", part)
|
|
}
|
|
return module, nil
|
|
}
|
|
|
|
func checkFingerprint(fp, of string) error {
|
|
if part, ok := strings.CutPrefix(fp, srcWord); !ok || !keys.IsHex64(part) {
|
|
return fmt.Errorf("wants: %s: %q is not a fingerprint of the new form, %s and 64 lowercase hex digits", of, fp, srcWord)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func checkDigest(digest, of string) error {
|
|
if !digestForm.MatchString(digest) {
|
|
return fmt.Errorf("wants: %s %q is not sha256:<64 lowercase hex digits>", of, digest)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func checkRule(rule int64, of string) error {
|
|
if rule < RuleBuildDone || rule > ruleRead {
|
|
return fmt.Errorf("wants: %s names the rule %d, which is not one of 1 to %d", of, rule, ruleRead)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// WantKey is the key, in the state wants, of a node's want for a module: `want.<node>.<module>`. A module named `node` is
|
|
// refused, since `want.<node>.node` is the node's own key.
|
|
func WantKey(node, module string) (string, error) {
|
|
if err := keys.CheckName("node", node); err != nil {
|
|
return "", err
|
|
}
|
|
part, err := moduleKeyPart(module)
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
if module == NodeWord {
|
|
return "", fmt.Errorf(`wants: the module name "node" is refused: want.%s.node is the node's own key`, node)
|
|
}
|
|
return seat.WantsByWantNodeModuleKey(node, part), nil
|
|
}
|
|
|
|
// WantNodeKey is the key of a node's own want: `want.<node>.node`.
|
|
func WantNodeKey(node string) (string, error) {
|
|
if err := keys.CheckName("node", node); err != nil {
|
|
return "", err
|
|
}
|
|
return seat.WantsByWantNodeNodeKey(node), nil
|
|
}
|
|
|
|
// ParseWantNodeKey is the inverse of WantNodeKey; it refuses a module's want key and any key of another form.
|
|
func ParseWantNodeKey(key string) (node string, err error) {
|
|
node, ok := seat.ParseWantsByWantNodeNodeKey(key)
|
|
if !ok || keys.CheckName("node", node) != nil {
|
|
return "", fmt.Errorf("wants: %q is not a node's own want key, want.<node>.node", key)
|
|
}
|
|
return node, nil
|
|
}
|
|
|
|
// ParseWantKey is the inverse of WantKey; it refuses a held key, the node's own want key and any key of another form.
|
|
func ParseWantKey(key string) (node, module string, err error) {
|
|
refused := fmt.Errorf("wants: %q is not a want key, want.<node>.<module>", key)
|
|
node, part, ok := seat.ParseWantsByWantNodeModuleKey(key)
|
|
if !ok || part == NodeWord || keys.CheckName("node", node) != nil {
|
|
return "", "", refused
|
|
}
|
|
if module, err = parseModuleKeyPart(part); err != nil {
|
|
return "", "", refused
|
|
}
|
|
return node, module, nil
|
|
}
|
|
|
|
// HeldKey is the key of a module's fingerprint the assigner holds: `held.<module>.<hex>`, the hex being the
|
|
// fingerprint's key part.
|
|
func HeldKey(module, fingerprint string) (string, error) {
|
|
if err := keys.CheckName("module", module); err != nil {
|
|
return "", err
|
|
}
|
|
if err := checkFingerprint(fingerprint, "a held key's fingerprint"); err != nil {
|
|
return "", err
|
|
}
|
|
return seat.WantsByHeldModuleFingerprintKey(module, strings.TrimPrefix(fingerprint, srcWord)), nil
|
|
}
|
|
|
|
// ParseHeldKey is the inverse of HeldKey: the module and the fingerprint (`src2:` and the hex).
|
|
func ParseHeldKey(key string) (module, fingerprint string, err error) {
|
|
module, part, ok := seat.ParseWantsByHeldModuleFingerprintKey(key)
|
|
if !ok || keys.CheckName("module", module) != nil || !keys.IsHex64(part) {
|
|
return "", "", fmt.Errorf("wants: %q is not a held key, held.<module>.<fingerprint hex>", key)
|
|
}
|
|
return module, srcWord + part, nil
|
|
}
|
|
|
|
func checkWant(w Want) error {
|
|
if w.Removed {
|
|
if w.Fp != "" || w.Composed != "" || w.Newest != "" || w.Rule != 0 || w.Backup != "" || w.Put || w.Hold || w.Self || w.Yes != "" || w.Release != "" {
|
|
return fmt.Errorf("wants: a removed want names no fingerprint, composition, rule, backup answer or put")
|
|
}
|
|
return nil
|
|
}
|
|
if w.Hold && !w.Put {
|
|
return fmt.Errorf("wants: only a put holds a want")
|
|
}
|
|
if w.Put && (w.Newest != "" || w.Rule != 0) {
|
|
return fmt.Errorf("wants: a put's want is held back by no rule")
|
|
}
|
|
if err := checkFingerprint(w.Fp, "a want's fingerprint"); err != nil {
|
|
return err
|
|
}
|
|
// A node the catalogue places composes its own modules (ADR 0547 §2): its want is Self and names the build alone. Any
|
|
// other want names the one composition it allows (ADR 0539 clause 1).
|
|
switch {
|
|
case w.Self && w.Composed != "":
|
|
return fmt.Errorf("wants: the want of %s says the node composes it, and names a composition", w.Fp)
|
|
case !w.Self && w.Composed == "":
|
|
return fmt.Errorf("wants: the want of %s names no composition: a want names the digest of the one composition it allows (ADR 0539 clause 1), unless the node composes it itself", w.Fp)
|
|
case w.Composed != "":
|
|
if err := checkDigest(w.Composed, "a want's composition digest"); err != nil {
|
|
return err
|
|
}
|
|
}
|
|
if w.Yes != "" {
|
|
if err := checkDigest(w.Yes, "the digest a want's yes allows"); err != nil {
|
|
return err
|
|
}
|
|
} else if w.Release != "" {
|
|
return fmt.Errorf("wants: the want of %s names the release %s and no yes it gave", w.Fp, w.Release)
|
|
}
|
|
switch w.Backup {
|
|
case "", BackupAgain, BackupSkip:
|
|
default:
|
|
return fmt.Errorf("wants: the backup answer %q is not %s or %s", w.Backup, BackupAgain, BackupSkip)
|
|
}
|
|
if w.Newest == "" && w.Rule == 0 {
|
|
return nil
|
|
}
|
|
if err := checkFingerprint(w.Newest, "a want's newest fingerprint"); err != nil {
|
|
return err
|
|
}
|
|
if w.Newest == w.Fp {
|
|
return fmt.Errorf("wants: a want at its newest fingerprint names no rule holding it back")
|
|
}
|
|
return checkRule(w.Rule, "a want held back")
|
|
}
|
|
|
|
// CheckWant refuses a want the codec refuses.
|
|
func CheckWant(w Want) error { return checkWant(w) }
|
|
|
|
// EncodeWant is w as JSON at the kept values' version; it refuses a fingerprint not of the new form, a removed want naming
|
|
// one, and a want that names no composition unless the node composes it itself.
|
|
func EncodeWant(w Want) ([]byte, error) {
|
|
if err := checkWant(w); err != nil {
|
|
return nil, err
|
|
}
|
|
w.V = keys.Version
|
|
return json.Marshal(w)
|
|
}
|
|
|
|
// DecodeWant reads a want; it refuses an unknown version (keys.ErrUnknownVersion), a field the contract does not know and
|
|
// what EncodeWant refuses.
|
|
func DecodeWant(data []byte) (Want, error) {
|
|
if err := keys.CheckVersion(data); err != nil {
|
|
return Want{}, err
|
|
}
|
|
w, err := seat.DecodeWantsByWantNodeModuleValue(data)
|
|
if err != nil {
|
|
return Want{}, fmt.Errorf("wants: value does not fit its shape: %w", err)
|
|
}
|
|
if err := checkWant(w); err != nil {
|
|
return Want{}, err
|
|
}
|
|
return w, nil
|
|
}
|
|
|
|
// SameWant says whether two wants are the same value, so the assigner writes only when they differ.
|
|
func SameWant(a, b Want) bool { return a == b }
|
|
|
|
func checkNodeWant(w NodeWant) error {
|
|
switch {
|
|
case w.Self && w.Composed != "":
|
|
return fmt.Errorf("wants: the node's own want says the node composes it, and names a composition")
|
|
case w.Self:
|
|
return nil
|
|
}
|
|
return checkDigest(w.Composed, "the node's own want's composition digest")
|
|
}
|
|
|
|
// EncodeNodeWant is w as JSON; it refuses a digest not of the sha256 form, and a want that names no composition unless it
|
|
// says the node composes its own (Self, ADR 0547 §2).
|
|
func EncodeNodeWant(w NodeWant) ([]byte, error) {
|
|
if err := checkNodeWant(w); err != nil {
|
|
return nil, err
|
|
}
|
|
w.V = keys.Version
|
|
return json.Marshal(w)
|
|
}
|
|
|
|
// DecodeNodeWant reads a node's own want; it refuses an unknown version, a field a node's own want does not have (a
|
|
// fingerprint among them), and what EncodeNodeWant refuses.
|
|
func DecodeNodeWant(data []byte) (NodeWant, error) {
|
|
if err := keys.CheckVersion(data); err != nil {
|
|
return NodeWant{}, err
|
|
}
|
|
w, err := seat.DecodeWantsByWantNodeNodeValue(data)
|
|
if err != nil {
|
|
return NodeWant{}, fmt.Errorf("wants: a node's own want does not fit its shape: %w", err)
|
|
}
|
|
if err := checkNodeWant(w); err != nil {
|
|
return NodeWant{}, err
|
|
}
|
|
return w, nil
|
|
}
|
|
|
|
func checkHeld(h Held) error { return keys.CheckName("node", h.Node) }
|
|
|
|
// EncodeHeld is h as JSON; it refuses a node name a key refuses.
|
|
func EncodeHeld(h Held) ([]byte, error) {
|
|
if err := checkHeld(h); err != nil {
|
|
return nil, err
|
|
}
|
|
h.V = keys.Version
|
|
return json.Marshal(h)
|
|
}
|
|
|
|
// DecodeHeld reads a hold; it refuses an unknown version and what EncodeHeld refuses.
|
|
func DecodeHeld(data []byte) (Held, error) {
|
|
if err := keys.CheckVersion(data); err != nil {
|
|
return Held{}, err
|
|
}
|
|
h, err := seat.DecodeWantsByHeldModuleFingerprintValue(data)
|
|
if err != nil {
|
|
return Held{}, fmt.Errorf("wants: value does not fit its shape: %w", err)
|
|
}
|
|
if err := checkHeld(h); err != nil {
|
|
return Held{}, err
|
|
}
|
|
return h, nil
|
|
}
|
|
|
|
// SameHeld says whether two holds are the same value.
|
|
func SameHeld(a, b Held) bool { return a == b }
|