The builder's reserved version reaches the build in the ask; a holder says when it takes and ends any ask, a builder's build included, so the watchman times every ask; the toolchains key names its program's digest; the checker may drop its own asks until its removal. step-progress and ask-taken name no keep and go on the shared events stream. The delivery SDK's neutral forms follow the part. Builds: design 47 G §472, §548, §549, §552, §573, §602, §603 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
244 lines
9.7 KiB
Go
244 lines
9.7 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
|
|
|
|
// 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"`
|
|
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
|
|
}
|
|
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 an ask's end, said by the build seat's holder on the node that ran it, whatever its asker (design 47 G
|
|
// §602): a pipeline step's end names its pipeline, step, module, artifact, commit and fingerprint; the end of any other
|
|
// ask names its asker, the ask, the node, the outcome and when, and neither commit nor fingerprint (G §548).
|
|
type StepEnded struct {
|
|
V int `json:"v"`
|
|
ID string `json:"id"`
|
|
Asker string `json:"asker"`
|
|
Ask string `json:"ask"`
|
|
Pipeline string `json:"pipeline,omitempty"`
|
|
Step string `json:"step,omitempty"`
|
|
Module string `json:"module,omitempty"`
|
|
Artifact string `json:"artifact,omitempty"`
|
|
Commit string `json:"commit,omitempty"`
|
|
Fingerprint string `json:"fingerprint,omitempty"`
|
|
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"`
|
|
At time.Time `json:"at,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, Asker: a.Asker, Ask: 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 e.Pipeline == "" {
|
|
// G §548, §602: the end of an ask outside a pipeline names its asker, the ask and when, and no commit or
|
|
// fingerprint.
|
|
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.Asker == "" || e.Ask == "" || e.At.IsZero() {
|
|
return fmt.Errorf("buildstep: the end of %s, an ask outside a pipeline, names no asker, ask or time", e.ID)
|
|
}
|
|
if e.Commit != "" || e.Fingerprint != "" {
|
|
return fmt.Errorf("buildstep: the end of %s names a commit or a fingerprint and no pipeline", e.ID)
|
|
}
|
|
return nil
|
|
}
|
|
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
|
|
}
|