Ported from the dev branch (192f6ab2, 4f013f44, dc0df1b5) into the package sdk/buildstep where they were built; the package is not named by a design line (see below). Builds: design 47 G §271 (a module claiming oci-artifact-registry but not its holder in the seat list is refused), §24 (a step's end is published on its node's subject), §416 (the step ask carries the kept results), §370 (the version). Not decided: the package of SD2 and SD3. G-9 §420 names sdk/steprun only for the step-run code (SD1); no line places the kept-artifact judgement or the step ask. Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
246 lines
9.3 KiB
Go
246 lines
9.3 KiB
Go
package buildstep
|
|
|
|
import (
|
|
"encoding/json"
|
|
"fmt"
|
|
"slices"
|
|
"strings"
|
|
"time"
|
|
|
|
meshkeys "git.novox.be/novox/mesh-sdk/go/keys"
|
|
)
|
|
|
|
// **A pipeline step, once.** The runner (seat mesh-pipeline-runner) asks each lint and test step of an artifact on the
|
|
// serving build seat's stream check, and the seat's holder says its end as the seat's event step-ended on its own node's
|
|
// subject (novox/hq ADR 0666 §7, §8, §21; design 47 *Pipeline steps and the policy*). These are the neutral forms of the
|
|
// part build-step's StepRun and StepEnded, which the three build modules share; the publish itself is the holder's.
|
|
|
|
// The pipeline steps a build seat runs.
|
|
const (
|
|
StepLint = "lint"
|
|
StepUnit = "unit"
|
|
StepIntegration = "integration"
|
|
)
|
|
|
|
// PipelineSteps are the steps a build seat serves, in a pipeline's order.
|
|
var PipelineSteps = []string{StepLint, StepUnit, StepIntegration}
|
|
|
|
// The outcomes a build seat says of a step: never passed for a step that ran nothing.
|
|
const (
|
|
OutcomePassed = "passed"
|
|
OutcomeFailed = "failed"
|
|
OutcomeNothingToRun = "nothing to run"
|
|
OutcomeCouldNotRun = "could not run"
|
|
)
|
|
|
|
// StepOutcomes are the outcomes a build seat may say.
|
|
var StepOutcomes = []string{OutcomePassed, OutcomeFailed, OutcomeNothingToRun, OutcomeCouldNotRun}
|
|
|
|
// StepEndedVersion is the layout version of a step's end.
|
|
const StepEndedVersion = 1
|
|
|
|
// StepNames are the names the registrations hold, which the lint step refuses fixed in code logic (ADR 0666 §5):
|
|
// carried in the ask, so the build module reads no other part for them.
|
|
type StepNames struct {
|
|
Modules []string `json:"modules"`
|
|
Repositories []string `json:"repositories"`
|
|
Branches []string `json:"branches"`
|
|
}
|
|
|
|
// KeptResult is a package's passing result at the digest of what its tests read (ADR 0666 §8).
|
|
type KeptResult struct {
|
|
Package string `json:"package"`
|
|
Digest string `json:"digest"`
|
|
Level string `json:"level"`
|
|
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
|
|
Pipeline string `json:"pipeline,omitempty"`
|
|
}
|
|
|
|
// TestCounts are how many tests a step ran and carried, per level.
|
|
type TestCounts struct {
|
|
Unit int `json:"unit,omitempty"`
|
|
Integration int `json:"integration,omitempty"`
|
|
}
|
|
|
|
// StepRun is one pipeline step of one artifact at one commit.
|
|
type StepRun struct {
|
|
Pipeline string `json:"pipeline"`
|
|
Step string `json:"step"`
|
|
Module string `json:"module"`
|
|
Artifact string `json:"artifact"`
|
|
Branch string `json:"branch,omitempty"`
|
|
Commit string `json:"commit"`
|
|
Revision int `json:"revision,omitempty"`
|
|
Fingerprint string `json:"fingerprint"`
|
|
Fetch Fetch `json:"fetch"`
|
|
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
|
|
Names StepNames `json:"names"`
|
|
Kept []KeptResult `json:"kept,omitempty"`
|
|
Rerun bool `json:"rerun,omitempty"`
|
|
By string `json:"by,omitempty"`
|
|
}
|
|
|
|
// Skips says whether the step runs no tests of pkg at digest, its kept result holding them.
|
|
func (r StepRun) Skips(pkg, digest string) bool {
|
|
return slices.ContainsFunc(r.Kept, func(k KeptResult) bool {
|
|
return k.Package == pkg && k.Digest == digest && k.Level == r.Step
|
|
})
|
|
}
|
|
|
|
func (r StepRun) check(id string) error {
|
|
if !slices.Contains(PipelineSteps, r.Step) {
|
|
return fmt.Errorf("buildstep: the step ask %s names the step %q, not %s", id, r.Step, strings.Join(PipelineSteps, ", "))
|
|
}
|
|
if r.Pipeline == "" {
|
|
return fmt.Errorf("buildstep: the step ask %s names no pipeline", id)
|
|
}
|
|
if err := meshkeys.CheckName("module", r.Module); err != nil {
|
|
return fmt.Errorf("the step ask %s: %w", id, err)
|
|
}
|
|
if mod, art, ok := strings.Cut(r.Artifact, ":"); !ok || mod != r.Module || art == "" {
|
|
return fmt.Errorf("buildstep: the step ask %s names the artifact %q, not %s:<artifact>", id, r.Artifact, r.Module)
|
|
}
|
|
if !askCommitOK.MatchString(r.Commit) {
|
|
return fmt.Errorf("buildstep: the step ask %s names no full commit (%q)", id, r.Commit)
|
|
}
|
|
if r.Fingerprint == "" {
|
|
return fmt.Errorf("buildstep: the step ask %s names no build-input fingerprint", id)
|
|
}
|
|
if err := r.Fetch.check(id); err != nil {
|
|
return err
|
|
}
|
|
var missing []string
|
|
for _, n := range []struct {
|
|
name string
|
|
list []string
|
|
}{{"modules", r.Names.Modules}, {"repositories", r.Names.Repositories}, {"branches", r.Names.Branches}} {
|
|
if len(n.list) == 0 {
|
|
missing = append(missing, n.name)
|
|
}
|
|
}
|
|
if len(missing) > 0 {
|
|
return fmt.Errorf("buildstep: the step ask %s names no %s of the registrations, which the lint step reads", id, strings.Join(missing, ", "))
|
|
}
|
|
if r.Rerun != (r.By != "") {
|
|
return fmt.Errorf("buildstep: the step ask %s is a rerun with no caller, or names a caller and is no rerun", id)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// StepEnded is a pipeline step's end, said by the build seat's holder on the node that ran it.
|
|
type StepEnded struct {
|
|
V int `json:"v"`
|
|
ID string `json:"id"`
|
|
Pipeline string `json:"pipeline"`
|
|
Step string `json:"step"`
|
|
Module string `json:"module"`
|
|
Artifact string `json:"artifact"`
|
|
Commit string `json:"commit"`
|
|
Fingerprint string `json:"fingerprint"`
|
|
Node string `json:"node"`
|
|
Outcome string `json:"outcome"`
|
|
Tests *TestCounts `json:"tests,omitempty"`
|
|
Carried []KeptResult `json:"carried,omitempty"`
|
|
Kept []KeptResult `json:"kept,omitempty"`
|
|
Said string `json:"said,omitempty"`
|
|
Output string `json:"output,omitempty"`
|
|
OutputObject string `json:"output-object,omitempty"`
|
|
Rerun bool `json:"rerun,omitempty"`
|
|
By string `json:"by,omitempty"`
|
|
Started time.Time `json:"started,omitzero"`
|
|
Ended time.Time `json:"ended,omitzero"`
|
|
}
|
|
|
|
// EndOf is the end of the step a holds, on node, with outcome: the ask's names copied, so the runner can match the ask,
|
|
// the commit and the fingerprint (ADR 0666 §21).
|
|
func EndOf(a StepAsk, node, outcome string) (StepEnded, error) {
|
|
if a.Step == nil {
|
|
return StepEnded{}, fmt.Errorf("buildstep: the ask %s is no pipeline step", a.ID)
|
|
}
|
|
s := a.Step
|
|
e := StepEnded{V: StepEndedVersion, ID: a.ID, Pipeline: s.Pipeline, Step: s.Step, Module: s.Module, Artifact: s.Artifact,
|
|
Commit: s.Commit, Fingerprint: s.Fingerprint, Node: node, Outcome: outcome, Rerun: s.Rerun, By: s.By}
|
|
return e, e.check()
|
|
}
|
|
|
|
func (e StepEnded) check() error {
|
|
if err := CheckAskID(e.ID); err != nil {
|
|
return err
|
|
}
|
|
if err := checkNode(e.Node); err != nil {
|
|
return err
|
|
}
|
|
if !slices.Contains(PipelineSteps, e.Step) {
|
|
return fmt.Errorf("buildstep: the end of %s names the step %q", e.ID, e.Step)
|
|
}
|
|
if !slices.Contains(StepOutcomes, e.Outcome) {
|
|
return fmt.Errorf("buildstep: the end of %s says %q, not one of %s", e.ID, e.Outcome, strings.Join(StepOutcomes, ", "))
|
|
}
|
|
if e.Pipeline == "" || e.Module == "" || e.Artifact == "" || !askCommitOK.MatchString(e.Commit) || e.Fingerprint == "" {
|
|
return fmt.Errorf("buildstep: the end of %s names no pipeline, module, artifact, full commit or fingerprint", e.ID)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// EncodeStepEnded is a step's end as its event's body; one that could not run or failed says why.
|
|
func EncodeStepEnded(e StepEnded) ([]byte, error) {
|
|
e.V = StepEndedVersion
|
|
if err := e.check(); err != nil {
|
|
return nil, err
|
|
}
|
|
if (e.Outcome == OutcomeCouldNotRun || e.Outcome == OutcomeFailed) && e.Said == "" {
|
|
return nil, fmt.Errorf("buildstep: the end of %s says %s and not why", e.ID, e.Outcome)
|
|
}
|
|
return json.Marshal(e)
|
|
}
|
|
|
|
// DecodeStepEnded reads a step's end heard on subject: the node it names must be the subject's, the one node whose
|
|
// holder's account may publish there (ADR 0363 §2, ADR 0666 §21).
|
|
func DecodeStepEnded(subject string, data []byte) (StepEnded, error) {
|
|
_, node, err := ParseStepEndedSubject(subject)
|
|
if err != nil {
|
|
return StepEnded{}, err
|
|
}
|
|
var e StepEnded
|
|
if err := json.Unmarshal(data, &e); err != nil {
|
|
return StepEnded{}, fmt.Errorf("buildstep: a step's end does not fit its shape: %w", err)
|
|
}
|
|
if e.V != StepEndedVersion {
|
|
return StepEnded{}, fmt.Errorf("%w: a step's end of version %d, this reader reads %d", ErrUnknownVersion, e.V, StepEndedVersion)
|
|
}
|
|
if err := e.check(); err != nil {
|
|
return StepEnded{}, err
|
|
}
|
|
if e.Node != node {
|
|
return StepEnded{}, fmt.Errorf("buildstep: the end of %s names the node %s and was said on %s's subject", e.ID, e.Node, node)
|
|
}
|
|
return e, nil
|
|
}
|
|
|
|
// StepEndedSubject is where the holder of a language's build seat on node says a step's end.
|
|
func StepEndedSubject(language, node string) (string, error) {
|
|
seat, err := BuildSeat(language)
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
if err := checkNode(node); err != nil {
|
|
return "", err
|
|
}
|
|
return "mesh.seat." + seat + ".event.step-ended." + node, nil
|
|
}
|
|
|
|
// ParseStepEndedSubject is the inverse of StepEndedSubject.
|
|
func ParseStepEndedSubject(subject string) (language, node string, err error) {
|
|
rest, ok := strings.CutPrefix(subject, "mesh.seat.node-build-")
|
|
if ok {
|
|
language, node, ok = strings.Cut(rest, ".event.step-ended.")
|
|
}
|
|
if !ok {
|
|
return "", "", fmt.Errorf("buildstep: %q is not a build seat's step-ended subject", subject)
|
|
}
|
|
if want, err := StepEndedSubject(language, node); err != nil || want != subject {
|
|
return "", "", fmt.Errorf("buildstep: %q is not a build seat's step-ended subject: %v", subject, err)
|
|
}
|
|
return language, node, nil
|
|
}
|