node-engine client: compose-candidate takes three key forms, built by the client and read by one parser (A-226b)

Builds: design 47 G (G-22 lead answers 2) A-226b; ADR 0593 §7
This commit is contained in:
2026-11-16 13:57:04 +01:00
parent c93229f23a
commit 2db6e5df49
5 changed files with 132 additions and 5 deletions
+85 -2
View File
@@ -10,6 +10,7 @@ import (
"errors"
"fmt"
"regexp"
"strconv"
"strings"
"time"
@@ -57,7 +58,7 @@ var ErrUnknownVersion = errors.New("node-engine: unknown compose-candidate answe
var nameOK = regexp.MustCompile(`^[-/_=a-zA-Z0-9]+$`)
func checkAsk(a seat.ComposeCandidateInput) error {
if _, _, err := ParseCompositionKey(a.Candidate); err != nil {
if _, err := ParseCandidateKey(a.Candidate); err != nil {
return fmt.Errorf("node-engine: a compose-candidate ask names no candidate: %w", err)
}
return nil
@@ -90,7 +91,7 @@ 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 := ParseCompositionKey(a.Candidate); err != nil {
if _, err := ParseCandidateKey(a.Candidate); err != nil {
return err
}
if a.Took < 0 {
@@ -216,3 +217,85 @@ func ParseCompositionKey(key string) (group, headsHash string, err error) {
}
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
}