Merge pull request 'Design 47 G start: node-engine contract fixes (A-226b, A-237b)' (#14) from fix/47-G-start-3 into main
This commit was merged in pull request #14.
This commit is contained in:
@@ -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
|
||||
}
|
||||
|
||||
@@ -113,3 +113,68 @@ func TestCompositionKeyRoundTripsAndRefuses(t *testing.T) {
|
||||
t.Error("a key with no group was made")
|
||||
}
|
||||
}
|
||||
|
||||
// A-226b: the three forms of a compose-candidate key are built by the client and read by one parser; a check's key reads as it
|
||||
// did, a revision's number is never mistaken for a heads hash, and what is none of them is refused naming it.
|
||||
func TestCandidateKeysOfTheThreeFormsRoundTripAndRefuse(t *testing.T) {
|
||||
check, _ := CompositionKey("fix/1.2", "0123456789ab")
|
||||
revision, err := RevisionKey("fix/1", 362)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
run, err := RunKey("r1")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for key, want := range map[string]Candidate{
|
||||
check: {Kind: CandidateCheck, Group: "fix/1.2", HeadsHash: "0123456789ab"},
|
||||
revision: {Kind: CandidateRevision, Branch: "fix/1", Revision: 362},
|
||||
run: {Kind: CandidateRun, Run: "r1"},
|
||||
"main.1": {Kind: CandidateRevision, Branch: "main", Revision: 1},
|
||||
} {
|
||||
if got, err := ParseCandidateKey(key); err != nil || got != want {
|
||||
t.Errorf("%q parsed as %+v (%v), want %+v", key, got, err, want)
|
||||
}
|
||||
}
|
||||
for _, bad := range []string{"", "nogroup", "run-", "g.0123456789AB", ".362", "a.b.362", "main.0", "main.-3", "main.0362", "main.123456789012x"} {
|
||||
if _, err := ParseCandidateKey(bad); err == nil {
|
||||
t.Errorf("%q was taken for a candidate key", bad)
|
||||
}
|
||||
}
|
||||
for _, bad := range []int64{0, -1, 100000000000} {
|
||||
if _, err := RevisionKey("main", bad); err == nil {
|
||||
t.Errorf("a key for revision %d was made", bad)
|
||||
}
|
||||
}
|
||||
if _, err := RevisionKey("", 1); err == nil {
|
||||
t.Error("a key with no branch was made")
|
||||
}
|
||||
if _, err := RunKey("a.b"); err == nil {
|
||||
t.Error("a run key with a dot was made")
|
||||
}
|
||||
// The ask and the answer accept all three.
|
||||
if _, err := EncodeAsk(seat.ComposeCandidateInput{Candidate: revision}); err != nil {
|
||||
t.Errorf("an ask naming a revision: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// A-237b: compose-candidate is a verb marked chunks: an ask carries the caller's call token, and an answer names the chunks the
|
||||
// composition input is sent in; the inline input stays for an ask with no token.
|
||||
func TestComposeCandidateAskAndAnswerCarryTheChunkedForm(t *testing.T) {
|
||||
key, _ := RevisionKey("main", 7)
|
||||
ask, err := EncodeAsk(seat.ComposeCandidateInput{Candidate: key, Input: true, Call: "0123456789abcdef0123456789abcdef"})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
back, err := DecodeAsk(ask)
|
||||
if err != nil || back.Call != "0123456789abcdef0123456789abcdef" || !back.Input {
|
||||
t.Errorf("the ask came back as %+v (%v)", back, err)
|
||||
}
|
||||
raw, err := EncodeAnswer(seat.ComposeCandidateAnswer{Node: "n1", Candidate: key, Verdict: Composed, Modules: []seat.Module{}, Own: seat.Module{Module: NodeWord, State: ModuleComposed, Digest: "sha256:" + strings.Repeat("a", 64)}, Chunks: 3})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if a, err := DecodeAnswer(raw); err != nil || a.Chunks != 3 || a.Input != nil {
|
||||
t.Errorf("the answer came back as %+v (%v)", a, err)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1349,7 +1349,9 @@ type ComposeAnswer struct {
|
||||
|
||||
// ComposeCandidateInput is what compose-candidate takes.
|
||||
type ComposeCandidateInput struct {
|
||||
// the key of the indexer's candidate, <group>.<heads hash>
|
||||
// 128 random bits the caller chooses: the subject token of the chunks and acknowledgements the composition input is sent in, whatever its size (design 47 G A-237b); an ask with input and no call is answered inline, as before the checker goes (G-6 section 321)
|
||||
Call string `json:"call,omitempty"`
|
||||
// the key of the candidate to compose: a check's candidate in the indexer, <group>.<heads hash>; a branch pipeline's catalog graph revision, <branch>.<revision> (the node-engine reads its entries through mesh-catalog.revision); or a run on request's, run-<id>; built and read by the seat's client (nodeengineclient)
|
||||
Candidate string `json:"candidate"`
|
||||
// also answer the composition input the candidate was composed from, for the sandbox path
|
||||
Input bool `json:"input,omitempty"`
|
||||
@@ -1359,7 +1361,9 @@ type ComposeCandidateInput struct {
|
||||
type ComposeCandidateAnswer struct {
|
||||
// the candidate's key
|
||||
Candidate string `json:"candidate"`
|
||||
// when asked: the composition input it composed from
|
||||
// when asked with input and a call token: how many chunks of at most 512 KiB carry the composition input, sent on the chunk subject of the call, each acknowledged by the caller (design 47 G A-237b)
|
||||
Chunks int64 `json:"chunks,omitempty"`
|
||||
// when asked without a call token: the composition input it composed from, inline, up to what one answer carries (the checker's form, kept until G removes the checker, G-6 section 321)
|
||||
Input map[string]any `json:"input,omitempty"`
|
||||
// every module placed on the node, sorted by name
|
||||
Modules []Module `json:"modules"`
|
||||
|
||||
@@ -176,7 +176,6 @@ func Glance(explanation string) error {
|
||||
// The bounds of an ask (novox/hq ADR 0234 §8, ADR 0259 §4).
|
||||
const (
|
||||
MostOptions = 4
|
||||
MostOpen = 3
|
||||
ApproveLasts = 24 * time.Hour
|
||||
DestroyLasts = 10 * time.Minute
|
||||
HeadlineLength = approval.HeadlineLength
|
||||
|
||||
@@ -56,7 +56,8 @@
|
||||
"entries"
|
||||
]
|
||||
},
|
||||
"optional": true
|
||||
"optional": true,
|
||||
"class": "read"
|
||||
},
|
||||
{
|
||||
"name": "show",
|
||||
@@ -67,7 +68,8 @@
|
||||
"answer": {
|
||||
"$ref": "#/defs/Held"
|
||||
},
|
||||
"optional": true
|
||||
"optional": true,
|
||||
"class": "read"
|
||||
},
|
||||
{
|
||||
"name": "check",
|
||||
@@ -122,7 +124,8 @@
|
||||
"differences"
|
||||
]
|
||||
},
|
||||
"optional": true
|
||||
"optional": true,
|
||||
"class": "read"
|
||||
},
|
||||
{
|
||||
"name": "orphans",
|
||||
@@ -147,7 +150,8 @@
|
||||
"entries"
|
||||
]
|
||||
},
|
||||
"optional": true
|
||||
"optional": true,
|
||||
"class": "read"
|
||||
},
|
||||
{
|
||||
"name": "create",
|
||||
|
||||
@@ -600,12 +600,16 @@
|
||||
"input": {
|
||||
"properties": {
|
||||
"candidate": {
|
||||
"description": "the key of the indexer's candidate, <group>.<heads hash>",
|
||||
"description": "the key of the candidate to compose: a check's candidate in the indexer, <group>.<heads hash>; a branch pipeline's catalog graph revision, <branch>.<revision> (the node-engine reads its entries through mesh-catalog.revision); or a run on request's, run-<id>; built and read by the seat's client (nodeengineclient)",
|
||||
"type": "string"
|
||||
},
|
||||
"input": {
|
||||
"description": "also answer the composition input the candidate was composed from, for the sandbox path",
|
||||
"type": "boolean"
|
||||
},
|
||||
"call": {
|
||||
"description": "128 random bits the caller chooses: the subject token of the chunks and acknowledgements the composition input is sent in, whatever its size (design 47 G A-237b); an ask with input and no call is answered inline, as before the checker goes (G-6 section 321)",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
@@ -658,7 +662,12 @@
|
||||
},
|
||||
"input": {
|
||||
"type": "object",
|
||||
"description": "when asked: the composition input it composed from"
|
||||
"description": "when asked without a call token: the composition input it composed from, inline, up to what one answer carries (the checker's form, kept until G removes the checker, G-6 section 321)"
|
||||
},
|
||||
"chunks": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"description": "when asked with input and a call token: how many chunks of at most 512 KiB carry the composition input, sent on the chunk subject of the call, each acknowledged by the caller (design 47 G A-237b)"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
@@ -671,6 +680,7 @@
|
||||
"took"
|
||||
]
|
||||
},
|
||||
"chunks": true,
|
||||
"class": "read"
|
||||
},
|
||||
{
|
||||
|
||||
Vendored
+6
-2
@@ -981,7 +981,9 @@ export interface ComposeAnswer {
|
||||
|
||||
/** is what compose-candidate takes. */
|
||||
export interface ComposeCandidateInput {
|
||||
/** the key of the indexer's candidate, <group>.<heads hash> */
|
||||
/** 128 random bits the caller chooses: the subject token of the chunks and acknowledgements the composition input is sent in, whatever its size (design 47 G A-237b); an ask with input and no call is answered inline, as before the checker goes (G-6 section 321) */
|
||||
"call"?: string;
|
||||
/** the key of the candidate to compose: a check's candidate in the indexer, <group>.<heads hash>; a branch pipeline's catalog graph revision, <branch>.<revision> (the node-engine reads its entries through mesh-catalog.revision); or a run on request's, run-<id>; built and read by the seat's client (nodeengineclient) */
|
||||
"candidate": string;
|
||||
/** also answer the composition input the candidate was composed from, for the sandbox path */
|
||||
"input"?: boolean;
|
||||
@@ -991,7 +993,9 @@ export interface ComposeCandidateInput {
|
||||
export interface ComposeCandidateAnswer {
|
||||
/** the candidate's key */
|
||||
"candidate": string;
|
||||
/** when asked: the composition input it composed from */
|
||||
/** when asked with input and a call token: how many chunks of at most 512 KiB carry the composition input, sent on the chunk subject of the call, each acknowledged by the caller (design 47 G A-237b) */
|
||||
"chunks"?: number;
|
||||
/** when asked without a call token: the composition input it composed from, inline, up to what one answer carries (the checker's form, kept until G removes the checker, G-6 section 321) */
|
||||
"input"?: Record<string, unknown>;
|
||||
/** every module placed on the node, sorted by name */
|
||||
"modules": Module[];
|
||||
|
||||
Reference in New Issue
Block a user