302 lines
13 KiB
Go
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
|
|
}
|