Files
mesh-delivery/modules/mesh-delivery-pipeline/internal/pipeline/failed.go
T
jschoubben 267bd0a9cb RN11: the runner says a failed head as the finding pipeline-failed
A required step that failed or could not run writes the finding of its commit, owned by the commit's author as the forge
records it (read through the seat git's pull); one with no known author has no owner and says why, written at the next step
end of that commit; a newer revision passing the steps clears it. The runner's finding writer is the held writer.

Builds: design 47 G §33, §540, A-191
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 05:53:20 +01:00

189 lines
7.4 KiB
Go

package pipeline
import (
"context"
"fmt"
"regexp"
"strings"
"time"
mcc "git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshconditionsclient"
condseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// PipelineFailedKind is the kind of the runner's finding of a failed head (design 47 G §33, §540).
const PipelineFailedKind = "pipeline-failed"
// forgeOwner is the form of an owner that names a commit's author as the forge does (design 47 G §540, §678).
var forgeOwner = regexp.MustCompile(`^forge:[A-Za-z0-9._-]+$`)
// Findings is the runner's finding writer as the failures use it: mesh-sdk's held writer of the seat mesh-conditions' finding.
type Findings interface {
Write(ctx context.Context, f condseat.Finding) error
Clear(ctx context.Context, scope, id, kind, why string) error
Held() []condseat.Finding
}
// Failures says a failed head (design 47 G §33, §540, A-191): a `required` step that failed, or ended `could not run`, is the
// finding `pipeline-failed` of its commit, naming the module, the branch, the commit and the steps, with the commit's author as
// its owner `forge:<account>`; a newer revision of that branch passing each of those steps clears it. The condition keeper
// raises it as the author's, and the operator's after two hours (§540).
type Failures struct {
Findings Findings
// Observer is the runner's own module name.
Observer string
// Author reads the forge's login of the commit's author through the seat git (the verb pull, by the commit that merged
// it); an error is a commit no pull request merged or a read that failed.
Author func(repository, commit string) (string, error)
Now func() time.Time
Logf func(string, ...any)
}
func (f *Failures) logf(format string, args ...any) {
if f.Logf != nil {
f.Logf(format, args...)
}
}
// failedSteps are the required steps of p that failed or could not run, the approval excepted: an approval's end is the
// operator's, not a failure of the commit.
func failedSteps(p seat.Pipeline) []seat.StepResult {
var out []seat.StepResult
for _, s := range p.Steps {
if s.Status == seat.StepResultStatusRequired && s.Step != seat.StepResultStepApproval &&
(s.Outcome == seat.StepResultOutcomeFailed || s.Outcome == seat.StepResultOutcomeCouldNotRun) {
out = append(out, s)
}
}
return out
}
func (f *Failures) held(commit string) *condseat.Finding {
for _, h := range f.Findings.Held() {
if h.Scope == mcc.ScopeMerge && h.ID == commit && h.Kind == PipelineFailedKind {
h := h
return &h
}
}
return nil
}
// StepEnded is what the end of step s of pipeline p says of its head: a failed required step writes the finding of its commit,
// a step of a commit already found failed that is not one writes its owner when it had none, and a passing required step clears
// the findings of the older revisions it makes good.
func (f *Failures) StepEnded(store Updater, p seat.Pipeline, s seat.StepResult) {
if f == nil || f.Findings == nil || p.Commit == "" {
return
}
ctx := context.Background()
switch {
case len(failedSteps(p)) > 0:
f.write(ctx, p)
case s.Outcome == seat.StepResultOutcomePassed || s.Outcome == seat.StepResultOutcomeCarried:
f.clearNewer(ctx, store, p)
}
}
// write writes p's commit's finding; the owner it held stays, and one it lacked is read again here, so the owner of a
// failed read is written at the next step end of that commit (A-191).
func (f *Failures) write(ctx context.Context, p seat.Pipeline) {
steps := failedSteps(p)
var names []string
for _, s := range steps {
names = append(names, strings.TrimSpace(s.Artifact+" "+s.Step)+" ("+s.Outcome+")")
}
now := time.Now().UTC()
if f.Now != nil {
now = f.Now().UTC()
}
owner, why := "", ""
if old := f.held(p.Commit); old != nil {
owner = old.Owner
}
if owner == "" {
owner, why = f.author(p)
}
explanation := fmt.Sprintf("The required steps %s of %s did not pass on the branch %s at the commit %s. A newer commit of the branch that passes them clears this.",
strings.Join(names, ", "), p.Module, p.Branch, p.Commit)
if why != "" {
explanation += " " + why
}
err := f.Findings.Write(ctx, condseat.Finding{Scope: mcc.ScopeMerge, ID: p.Commit, Kind: PipelineFailedKind, Severity: condseat.FindingSeverityWarning,
Summary: fmt.Sprintf("%s on %s at %s: %s", p.Module, p.Branch, p.Commit, strings.Join(names, ", ")),
Headline: fmt.Sprintf("A required step of %s failed on %s", p.Module, p.Branch),
Explanation: explanation, Needs: "a newer commit of " + p.Branch + " that passes " + strings.Join(names, ", "),
Owner: owner, Source: "pipeline-runner." + PipelineFailedKind, Observer: f.Observer, At: now,
Subject: condseat.Subject{Scope: mcc.ScopeMerge, ID: p.Commit}})
if err != nil {
f.logf("the finding %s of %s at %s is not written: %v", PipelineFailedKind, p.Module, p.Commit, err)
}
}
// author is the finding's owner `forge:<account>` and, when it has none, why it has none (A-191).
func (f *Failures) author(p seat.Pipeline) (string, string) {
if f.Author == nil {
return "", "The commit's author is not read, so the finding has no owner."
}
account, err := f.Author(p.Repository, p.Commit)
if err != nil {
f.logf("the author of %s in %s is not read, so its finding %s has no owner: %v", p.Commit, p.Repository, PipelineFailedKind, err)
return "", "The commit's author is not known (" + err.Error() + "), so the finding has no owner."
}
if !forgeOwner.MatchString("forge:" + account) {
f.logf("the author %q of %s is no forge account name, so its finding %s has no owner", account, p.Commit, PipelineFailedKind)
return "", "The commit's author is not known as a forge account, so the finding has no owner."
}
return "forge:" + account, ""
}
// clearNewer clears the finding of each older commit of p's module and branch whose every failed step a revision newer than it
// has passed (§33: cleared when a newer revision of that branch passes that step).
func (f *Failures) clearNewer(ctx context.Context, store Updater, p seat.Pipeline) {
pkeys, err := store.Keys(keys.EscapeName(p.Branch) + ".*." + p.Module)
if err != nil {
f.logf("the pipelines of %s on %s are not listed, so no finding %s is cleared: %v", p.Module, p.Branch, PipelineFailedKind, err)
return
}
var all []seat.Pipeline
for _, k := range pkeys {
if q, _, err := store.Get(k); err == nil {
all = append(all, q)
}
}
for _, old := range all {
if old.Source >= p.Source || f.held(old.Commit) == nil {
continue
}
failed := failedSteps(old)
if len(failed) == 0 {
continue
}
made := true
for _, s := range failed {
made = made && passedAfter(all, old, s)
}
if made {
if err := f.Findings.Clear(ctx, mcc.ScopeMerge, old.Commit, PipelineFailedKind, "a newer revision of "+p.Branch+" passes its steps"); err != nil {
f.logf("the finding %s of %s at %s is not cleared: %v", PipelineFailedKind, p.Module, old.Commit, err)
}
}
}
}
// passedAfter says whether a pipeline newer than old passed the step s of old.
func passedAfter(all []seat.Pipeline, old seat.Pipeline, s seat.StepResult) bool {
for _, q := range all {
if q.Source <= old.Source {
continue
}
for _, t := range q.Steps {
if t.Artifact == s.Artifact && t.Step == s.Step && (t.Outcome == seat.StepResultOutcomePassed || t.Outcome == seat.StepResultOutcomeCarried) {
return true
}
}
}
return false
}