// 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, `.`, 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, .", 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 // `.` (CompositionKey), a branch pipeline's catalog graph revision `.` (RevisionKey) // and a run on request's `run-` (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: `.`, 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-`, 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-` 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, ., . or run-", 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 }