Files
mesh-contracts/go/clients/nodeengineclient/client.go
T
2026-11-16 13:57:04 +01:00

302 lines
13 KiB
Go

// Package nodeengineclient is the node-engine seat's client (novox/hq ADR 0627 §1, ADR 0625 §4): the checks its callers
// share over the verb compose-candidate's ask and answer (ADR 0593 §7, §9), over the seat's generated contract. The
// node-engine encodes its answer through it, and the checker and the assigner read answers and the asker's bound
// through it. The composing is the node-engine's own; the call is the caller's own, so it holds no transport.
package nodeengineclient
import (
"bytes"
"encoding/json"
"errors"
"fmt"
"regexp"
"strconv"
"strings"
"time"
seat "git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"git.novox.be/novox/mesh-sdk/go/keys"
)
const (
// AnswerBound is the default bound an asker of compose-candidate waits for a node's answer (the checker's setting
// compose-answer-bound, ADR 0593 §7, §9).
AnswerBound = 60 * time.Second
// NoAnswer is the words a check's verdict names a node with that did not answer within the bound (ADR 0593 §9).
NoAnswer = "not composed on that node: no answer"
// Composed and Refused are an answer's verdict: no module and not the node's own composition is refused by the
// candidate, or at least one is (or the node could not compose with it at all, the answer's Refused).
Composed = "composed"
Refused = "refused"
// Unready is the verdict of a node that cannot compose yet (its shadow not ready, its agent starting): no module is
// named, Refused says why in words, and the checker takes it as a node that did not answer (NoAnswer), deciding by
// this verdict and never by the words.
Unready = "unready"
// NotJudged is the verdict for a node the checker's sandbox composed and could not judge (an older node-engine's
// input that does not say how it composes, ADR 0593 §9): no module is named, Refused says why in words, and the
// checker names the node with them and passes the check with that warning (ADR 0601 §4: a contract is a field, not
// a phrase).
NotJudged = "not-judged"
// The states of one module's composition with the candidate: composed (Digest set), refused by the candidate
// (Words set), or held, refused without the candidate too (Words set), which counts toward no verdict.
ModuleComposed = "composed"
ModuleRefused = "refused"
ModuleHeld = "held"
// Own is the Module name of the node's own composition in an answer.
Own = "node"
// Version is the version an answer is written at and the only one read.
Version = 1
)
// ErrUnknownVersion is what DecodeAnswer returns for an answer whose version is missing or not Version.
var ErrUnknownVersion = errors.New("node-engine: unknown compose-candidate answer version")
var nameOK = regexp.MustCompile(`^[-/_=a-zA-Z0-9]+$`)
func checkAsk(a seat.ComposeCandidateInput) error {
if _, err := ParseCandidateKey(a.Candidate); err != nil {
return fmt.Errorf("node-engine: a compose-candidate ask names no candidate: %w", err)
}
return nil
}
func checkModule(m seat.Module, node string) error {
if m.Module == "" {
return fmt.Errorf("node-engine: a module's composition on %s names no module", node)
}
switch m.State {
case ModuleComposed:
if m.Digest == "" {
return fmt.Errorf("node-engine: %s is composed on %s and names no digest", m.Module, node)
}
case ModuleRefused, ModuleHeld:
if m.Words == "" {
return fmt.Errorf("node-engine: %s is %s on %s and says no why", m.Module, m.State, node)
}
default:
return fmt.Errorf("node-engine: %s on %s is %q, neither %s, %s nor %s", m.Module, node, m.State,
ModuleComposed, ModuleRefused, ModuleHeld)
}
return nil
}
// CheckAnswer refuses an answer naming no node or candidate, a negative time taken, an unknown module state, a composed
// module without a digest, a refused or held one without words, modules not sorted and each once, a refusal of the
// whole naming modules, an unready or not-judged one saying no why, and a verdict the modules do not give.
func CheckAnswer(a seat.ComposeCandidateAnswer) error {
if a.Node == "" || !nameOK.MatchString(a.Node) {
return fmt.Errorf("node-engine: the answer's node name %q is empty or holds a dot, a wildcard, whitespace or a character a key refuses", a.Node)
}
if _, err := ParseCandidateKey(a.Candidate); err != nil {
return err
}
if a.Took < 0 {
return fmt.Errorf("node-engine: the answer of %s took %d ms", a.Node, a.Took)
}
if (a.Verdict == Unready || a.Verdict == NotJudged) && a.Refused == "" {
return fmt.Errorf("node-engine: %s's answer is %s and says no why", a.Node, a.Verdict)
}
if a.Refused != "" {
if len(a.Modules) > 0 || a.Verdict != Refused && a.Verdict != Unready && a.Verdict != NotJudged {
return fmt.Errorf("node-engine: %s could not compose the candidate (%s), and its answer names modules or is neither %s, %s nor %s",
a.Node, a.Refused, Refused, Unready, NotJudged)
}
return nil
}
refused := false
for i, m := range append([]seat.Module{a.Own}, a.Modules...) {
if err := checkModule(m, a.Node); err != nil {
return err
}
if i > 1 && a.Modules[i-2].Module >= m.Module {
return fmt.Errorf("node-engine: the modules of %s's answer are not sorted and each once (%s after %s)", a.Node, m.Module, a.Modules[i-2].Module)
}
refused = refused || m.State == ModuleRefused
}
switch {
case a.Own.Module != Own:
return fmt.Errorf("node-engine: the node's own composition in %s's answer is named %q, not %q", a.Node, a.Own.Module, Own)
case refused && a.Verdict != Refused:
return fmt.Errorf("node-engine: %s's answer refuses a module and its verdict is %q", a.Node, a.Verdict)
case !refused && a.Verdict != Composed:
return fmt.Errorf("node-engine: %s's answer refuses no module and its verdict is %q", a.Node, a.Verdict)
}
return nil
}
// strictDecode reads data into v, refusing an unknown key.
func strictDecode(data []byte, v any, what string) error {
d := json.NewDecoder(bytes.NewReader(data))
d.DisallowUnknownFields()
d.UseNumber() // a number in an object the contract leaves open (the composition input) keeps its digits as written
if err := d.Decode(v); err != nil {
return fmt.Errorf("node-engine: %s does not fit its shape: %w", what, err)
}
return nil
}
// EncodeAsk is a as JSON; it refuses an ask naming no candidate key.
func EncodeAsk(a seat.ComposeCandidateInput) ([]byte, error) {
if err := checkAsk(a); err != nil {
return nil, err
}
return json.Marshal(a)
}
// DecodeAsk reads an ask strictly; it refuses an unknown key and what EncodeAsk refuses.
func DecodeAsk(data []byte) (seat.ComposeCandidateInput, error) {
var a seat.ComposeCandidateInput
if err := strictDecode(data, &a, "a compose-candidate ask"); err != nil {
return seat.ComposeCandidateInput{}, err
}
return a, checkAsk(a)
}
// EncodeAnswer is a as JSON at Version; it refuses what CheckAnswer refuses.
func EncodeAnswer(a seat.ComposeCandidateAnswer) ([]byte, error) {
if err := CheckAnswer(a); err != nil {
return nil, err
}
a.V = Version
return json.Marshal(a)
}
// DecodeAnswer reads an answer strictly; it refuses an unknown version (ErrUnknownVersion), an unknown key and what
// CheckAnswer refuses.
func DecodeAnswer(data []byte) (seat.ComposeCandidateAnswer, error) {
var probe struct {
V *int64 `json:"v"`
}
if err := json.Unmarshal(data, &probe); err != nil {
return seat.ComposeCandidateAnswer{}, fmt.Errorf("node-engine: a compose-candidate answer is not JSON: %w", err)
}
if probe.V == nil || *probe.V != Version {
return seat.ComposeCandidateAnswer{}, fmt.Errorf("%w: this reader reads %d", ErrUnknownVersion, Version)
}
var a seat.ComposeCandidateAnswer
if err := strictDecode(data, &a, "a compose-candidate answer"); err != nil {
return seat.ComposeCandidateAnswer{}, err
}
return a, CheckAnswer(a)
}
var heads12 = regexp.MustCompile(`^[0-9a-f]{12}$`)
// CompositionKey is the key of a candidate the node is asked to compose: the group's check at its heads, `<escaped
// group>.<heads hash>`, the group escaped as a key part and the heads hash 12 lowercase hex digits (the checker's verdict
// key of the same check).
func CompositionKey(group, headsHash string) (string, error) {
if group == "" {
return "", errors.New("node-engine: the group name is empty")
}
if !heads12.MatchString(headsHash) {
return "", fmt.Errorf("node-engine: %q is not a heads hash, 12 lowercase hex digits", headsHash)
}
return keys.EscapeName(group) + "." + headsHash, nil
}
// ParseCompositionKey is the inverse of CompositionKey; it refuses a key that is not one, naming it.
func ParseCompositionKey(key string) (group, headsHash string, err error) {
i := strings.LastIndex(key, ".")
if i < 0 {
return "", "", fmt.Errorf("node-engine: %q is not a composition key, <group>.<heads hash>", key)
}
part, headsHash := key[:i], key[i+1:]
if !heads12.MatchString(headsHash) {
return "", "", fmt.Errorf("node-engine: %q is not a composition key: %q is not a heads hash, 12 lowercase hex digits", key, headsHash)
}
if part == "" || strings.Contains(part, ".") {
return "", "", fmt.Errorf("node-engine: %q is not a composition key: the group part is empty or holds a dot", key)
}
if group, err = keys.UnescapeName(part); err != nil {
return "", "", fmt.Errorf("node-engine: %q is not a composition key: %w", key, err)
}
return group, headsHash, nil
}
// The three forms of the key `compose-candidate` takes (ADR 0593 §7; design 47 G A-226, A-226b): a check's candidate
// `<group>.<heads hash>` (CompositionKey), a branch pipeline's catalog graph revision `<branch>.<revision>` (RevisionKey)
// and a run on request's `run-<id>` (RunKey). Every caller builds its key with the builders and the node-engine reads it with
// ParseCandidateKey, so no caller writes a key by hand.
// The kinds of candidate a key names.
const (
CandidateCheck = "check"
CandidateRevision = "revision"
CandidateRun = "run"
)
const runKeyPrefix = "run-"
// maxRevision keeps a revision number from reading as a 12-digit heads hash: 12 decimal digits are 12 lowercase hex digits.
const maxRevision = 99999999999
// Candidate is what a key names: Kind says which of the others are set.
type Candidate struct {
Kind string
// Group and HeadsHash of a check's candidate.
Group, HeadsHash string
// Branch and Revision of a branch pipeline's catalog graph revision.
Branch string
Revision int64
// Run is a run on request's id.
Run string
}
// RevisionKey is the key of a branch's catalog graph revision: `<escaped branch>.<revision>`, the branch escaped as a key
// part as the pipeline key escapes it, the revision a positive number of at most 11 digits.
func RevisionKey(branch string, revision int64) (string, error) {
if branch == "" {
return "", errors.New("node-engine: the branch name is empty")
}
if revision <= 0 || revision > maxRevision {
return "", fmt.Errorf("node-engine: %d is not a catalog graph revision, a positive number of at most 11 digits", revision)
}
return keys.EscapeName(branch) + "." + strconv.FormatInt(revision, 10), nil
}
// RunKey is the key of a run on request's candidate: `run-<id>`, the id one key part with no dot.
func RunKey(run string) (string, error) {
if run == "" || strings.ContainsAny(run, ". \t\n") {
return "", fmt.Errorf("node-engine: %q is no run's id: it is empty or holds a dot or whitespace", run)
}
return runKeyPrefix + run, nil
}
// ParseCandidateKey is the inverse of the three builders; it refuses a key that is none of them, naming it. A key with a
// dot whose last part is 12 lowercase hex digits is a check's (a revision number has at most 11 digits), one with a dot and a
// number is a revision's, and `run-<id>` with no dot is a run's.
func ParseCandidateKey(key string) (Candidate, error) {
if !strings.Contains(key, ".") {
if run, ok := strings.CutPrefix(key, runKeyPrefix); ok && run != "" && !strings.ContainsAny(run, " \t\n") {
return Candidate{Kind: CandidateRun, Run: run}, nil
}
return Candidate{}, fmt.Errorf("node-engine: %q is not a candidate key, <group>.<heads hash>, <branch>.<revision> or run-<id>", key)
}
i := strings.LastIndex(key, ".")
if heads12.MatchString(key[i+1:]) {
group, headsHash, err := ParseCompositionKey(key)
if err != nil {
return Candidate{}, err
}
return Candidate{Kind: CandidateCheck, Group: group, HeadsHash: headsHash}, nil
}
part, number := key[:i], key[i+1:]
revision, err := strconv.ParseInt(number, 10, 64)
if err != nil || revision <= 0 || revision > maxRevision || strconv.FormatInt(revision, 10) != number {
return Candidate{}, fmt.Errorf("node-engine: %q is not a candidate key: %q is neither a heads hash, 12 lowercase hex digits, nor a revision number", key, number)
}
if part == "" || strings.Contains(part, ".") {
return Candidate{}, fmt.Errorf("node-engine: %q is not a candidate key: the branch part is empty or holds a dot", key)
}
branch, err := keys.UnescapeName(part)
if err != nil {
return Candidate{}, fmt.Errorf("node-engine: %q is not a candidate key: %w", key, err)
}
return Candidate{Kind: CandidateRevision, Branch: branch, Revision: revision}, nil
}