Files
mesh-delivery/modules/mesh-delivery-pipeline/internal/pipeline/verbs.go
T
2026-11-16 13:38:57 +01:00

430 lines
17 KiB
Go

package pipeline
import (
"errors"
"fmt"
"strings"
"time"
builds "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshbuilds"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
wants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
nodebuildgo "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/views"
)
// Verbs are the runner's write verbs `review`, `rerun`, `accept` and `cancel`, answered by its own process (design 47 G §22,
// §70, §482, A-107): each writes the state pipelines by compare-and-set on the revision read and says its event as the
// hearer does for a step's end. The caller each takes is the one the bus proved.
type Verbs struct {
Hearer *Hearer
// Starter asks a step again (rerun), as it asks the steps of a start; View reads a branch's catalog half for the ask.
Starter *Starter
View func(branch string) (Half, bool)
// Candidate reads a run's candidate's catalog half, its group `run-<id>`, on branch at the revision its pipeline was placed
// from, for a rerun of a run's step (A-222): a run's steps are the candidate's, never the branch's.
Candidate func(group, branch string, revision int64) (Half, error)
// Acts records a hand act before the verb does it (rerun, accept, cancel); a nil Acts refuses the verb, nothing recorded.
Acts views.HandActs
// Drop drops the bound of an ask a cancelled pipeline no longer waits on.
Drop func(ask string) error
}
func (v Verbs) now() time.Time { return v.Hearer.now() }
func (v Verbs) record(verb, what, why string) error {
if v.Acts == nil {
return errors.New("no way to record a hand act is given: nothing was done")
}
if strings.TrimSpace(why) == "" {
return fmt.Errorf("%s says why: nothing was done", verb)
}
if err := v.Acts.RecordHandAct(views.HandAct{What: what, Why: why, Verb: seat.Seat + "." + verb}); err != nil {
return fmt.Errorf("the hand act is not recorded, so nothing was done: %w", err)
}
return nil
}
// change writes one change of a pipeline by compare-and-set, read again when another write came between, and says what it
// became: the step-ended of the step mutate changed (its index, -1 for none), the wait of an approval asked and the
// pipeline-ended of a pipeline it ended. It returns the written pipeline and the changed step.
func (v Verbs) change(key, event string, record func() error, mutate func(p *seat.Pipeline, now time.Time) (int, error)) (seat.Pipeline, int, error) {
h := v.Hearer
recorded := false
for {
p, rev, err := h.Store.Get(key)
if err != nil {
return p, -1, fmt.Errorf("the pipeline %s is not read: %w", key, err)
}
now := h.now()
i, err := mutate(&p, now)
if err != nil {
return p, -1, err
}
// The hand act is recorded once the verb is valid and before it writes (ADR 0565 clause 11); a refused verb records none.
if record != nil && !recorded {
if err := record(); err != nil {
return p, -1, err
}
recorded = true
}
asked, err := askApproval(key, &p, now, h.Asker)
if err != nil {
return p, i, err
}
ended := endPipeline(&p, now)
if i >= 0 && event == seat.EventStepEnded {
p.Unlogged = append(p.Unlogged, endEntry(key, p.Steps[i], now))
}
if _, err := h.Store.Update(key, p, rev); errors.Is(err, ErrChanged) {
continue
} else if err != nil {
return p, i, fmt.Errorf("pipeline %s cannot be written: %w", key, err)
}
if i >= 0 {
if err := h.say(event, p, &p.Steps[i]); err != nil {
return p, i, fmt.Errorf("pipeline %s's %s is written but not said: %w", key, event, err)
}
if event == seat.EventStepEnded {
h.appendUnlogged(key)
}
}
return p, i, h.said(p, asked, ended)
}
}
// Review takes a code review's result for a commit and fingerprint from caller, the bus's proof, refusing none for
// authorship (§482): it ends the placed review step of each running pipeline of the module at that commit and fingerprint,
// recording caller in the step's result. It answers the first such pipeline; a review no pipeline waits on is refused.
func (v Verbs) Review(caller string, in seat.ReviewInput) (seat.ReviewAnswer, error) {
if in.Outcome != seat.ReviewInputOutcomePassed && in.Outcome != seat.ReviewInputOutcomeFailed {
return seat.ReviewAnswer{}, fmt.Errorf("a review ends %q or %q, not %q", seat.ReviewInputOutcomePassed, seat.ReviewInputOutcomeFailed, in.Outcome)
}
keys, err := v.Hearer.Store.Keys("*.*.*")
if err != nil {
return seat.ReviewAnswer{}, fmt.Errorf("the pipelines are not listed: %w", err)
}
var answer *seat.ReviewAnswer
for _, key := range keys {
p, _, err := v.Hearer.Store.Get(key)
if err != nil || p.Module != in.Module || p.Commit != in.Commit || p.Fingerprint != in.Fingerprint || reviewWaiting(p) < 0 {
continue
}
written, i, err := v.change(key, seat.EventStepEnded, nil, func(p *seat.Pipeline, now time.Time) (int, error) {
i := reviewWaiting(*p)
if i < 0 {
return -1, fmt.Errorf("%s has no review step waiting any more", key)
}
s := &p.Steps[i]
s.Outcome, s.By, s.Why, s.Ended = in.Outcome, caller, in.Said, &now
return i, nil
})
if err != nil {
return seat.ReviewAnswer{}, err
}
if answer == nil {
answer = &seat.ReviewAnswer{Pipeline: key, Result: written.Steps[i]}
}
}
if answer == nil {
return seat.ReviewAnswer{}, fmt.Errorf("no running pipeline of %s at %s (%s) waits on a review", in.Module, in.Commit, in.Fingerprint)
}
return *answer, nil
}
func reviewWaiting(p seat.Pipeline) int {
if p.Outcome != seat.PipelineOutcomeRunning {
return -1
}
for i, s := range p.Steps {
if s.Step == seat.StepResultStepReview && s.Outcome == seat.StepResultOutcomeWaiting {
return i
}
}
return -1
}
// stepOf is the index of the step named, and of its artifact when one is named.
func stepOf(p seat.Pipeline, step, artifact string) (int, error) {
found := -1
for i, s := range p.Steps {
if s.Step != step || (artifact != "" && s.Artifact != artifact) {
continue
}
if found >= 0 {
return -1, fmt.Errorf("%s names more than one %s step: name its artifact", p.Pipeline, step)
}
found = i
}
if found < 0 {
return -1, fmt.Errorf("%s has no %s step", p.Pipeline, step)
}
return found, nil
}
// Accept accepts a failed `optional` step, recorded in the hand-act log first with who and why (§30, §394).
func (v Verbs) Accept(caller string, in seat.AcceptInput) (seat.AcceptAnswer, error) {
p, i, err := v.change(in.Pipeline, seat.EventStepEnded, func() error {
return v.record(seat.VerbAccept, fmt.Sprintf("accepted the failed %s step of %s", in.Step, in.Pipeline), in.Why)
}, func(p *seat.Pipeline, now time.Time) (int, error) {
i, err := stepOf(*p, in.Step, in.Artifact)
if err != nil {
return -1, err
}
s := &p.Steps[i]
if s.Status != seat.StepResultStatusOptional || s.Outcome != seat.StepResultOutcomeFailed {
return -1, fmt.Errorf("only a failed optional step is accepted: the %s step of %s is %s and %s", in.Step, in.Pipeline, s.Status, s.Outcome)
}
s.Outcome, s.Accepted, s.Ended = seat.StepResultOutcomeAccepted, &seat.Accepted{At: &now, By: caller, Why: in.Why}, &now
return i, nil
})
if err != nil {
return seat.AcceptAnswer{}, err
}
return seat.AcceptAnswer{Result: p.Steps[i]}, nil
}
// Cancel ends a running pipeline `cancelled`, each step not ended cancelled and the bound of each ask dropped, recorded in
// the hand-act log first (§394); it says pipeline-ended.
func (v Verbs) Cancel(caller string, in seat.CancelInput) (seat.CancelAnswer, error) {
h := v.Hearer
recorded := false
for {
p, rev, err := h.Store.Get(in.Pipeline)
if err != nil {
return seat.CancelAnswer{}, fmt.Errorf("the pipeline %s is not read: %w", in.Pipeline, err)
}
if p.Outcome != seat.PipelineOutcomeRunning {
return seat.CancelAnswer{}, fmt.Errorf("the pipeline %s is %s, not running", in.Pipeline, p.Outcome)
}
if !recorded {
if err := v.record(seat.VerbCancel, "cancelled the pipeline "+in.Pipeline, in.Why); err != nil {
return seat.CancelAnswer{}, err
}
recorded = true
}
now := h.now()
var drop []string
for i := range p.Steps {
s := &p.Steps[i]
if s.Outcome != seat.StepResultOutcomeRunning && s.Outcome != seat.StepResultOutcomeWaiting {
continue
}
if s.Ask != "" {
drop = append(drop, s.Ask)
}
s.Outcome, s.By, s.Why, s.Ended = seat.StepResultOutcomeCancelled, caller, in.Why, &now
}
p.Outcome, p.Why, p.Ended = seat.PipelineOutcomeCancelled, in.Why, &now
p.EndCount++
if _, err := h.Store.Update(in.Pipeline, p, rev); errors.Is(err, ErrChanged) {
continue
} else if err != nil {
return seat.CancelAnswer{}, fmt.Errorf("pipeline %s cannot be written: %w", in.Pipeline, err)
}
if v.Drop != nil {
for _, ask := range drop {
if err := v.Drop(ask); err != nil {
h.logf("the bound of ask %s of the cancelled %s is not dropped: %v", ask, in.Pipeline, err)
}
}
}
return seat.CancelAnswer{Pipeline: p}, h.said(p, false, true)
}
}
// Rerun asks one step again, recorded in the hand-act log first (§22, §39): the step goes back to running under a new ask,
// the ask saying it is a rerun and the caller the bus proved; a failed pipeline runs again and ends once more with its end
// count one higher (§325), an approval never asked waiting again. A review waits again; an approval is asked again by
// `ask-again`.
func (v Verbs) Rerun(caller string, in seat.RerunInput) (seat.RerunAnswer, error) {
if in.Step == seat.StepResultStepApproval {
return seat.RerunAnswer{}, errors.New("an approval is asked again by ask-again, not rerun")
}
var ask *Asked
p, _, err := v.change(in.Pipeline, seat.EventStepStarted, func() error {
return v.record(seat.VerbRerun, fmt.Sprintf("asked the %s step of %s again", in.Step, in.Pipeline), in.Why)
}, func(p *seat.Pipeline, now time.Time) (int, error) {
ask = nil
switch p.Outcome {
case seat.PipelineOutcomeCancelled, seat.PipelineOutcomeSuperseded:
return -1, fmt.Errorf("the pipeline %s is %s: a step of it is not asked again", p.Pipeline, p.Outcome)
}
i, err := stepOf(*p, in.Step, in.Artifact)
if err != nil {
return -1, err
}
s := &p.Steps[i]
if s.Outcome == seat.StepResultOutcomeRunning {
return -1, fmt.Errorf("the %s step of %s is running: it is not asked again", in.Step, p.Pipeline)
}
if s.Seat != "" {
if ask, err = v.askOf(*p, *s, caller, now); err != nil {
return -1, err
}
}
*s = seat.StepResult{Step: s.Step, Artifact: s.Artifact, Status: s.Status, Fingerprint: s.Fingerprint, Seat: s.Seat,
Outcome: seat.StepResultOutcomeWaiting, By: caller, Rerun: true}
if ask != nil {
s.Outcome, s.Started, s.Ask = seat.StepResultOutcomeRunning, &now, ask.ID
}
// The pipeline runs again; an approval never asked waits again, to be asked when the step passes.
if p.Outcome != seat.PipelineOutcomeRunning {
p.Outcome, p.Why, p.Ended = seat.PipelineOutcomeRunning, "", nil
}
for j := range p.Steps {
if p.Steps[j].Step == seat.StepResultStepApproval && p.Steps[j].Outcome == seat.StepResultOutcomeNotAsked {
p.Steps[j].Outcome, p.Steps[j].Why = seat.StepResultOutcomeWaiting, ""
}
}
if ask == nil {
return -1, nil
}
return i, nil
})
if err != nil {
return seat.RerunAnswer{}, err
}
v.Hearer.pin(p) // a pipeline that runs again keeps its revision again (A-449)
if ask != nil {
v.Starter.carry(in.Pipeline, []Asked{*ask})
if err := askAll(v.Starter.Steps, v.Starter.Arm, in.Pipeline, []Asked{*ask}, v.Starter.recovered(in.Pipeline, p.Commit)); err != nil {
return seat.RerunAnswer{}, fmt.Errorf("the step is written running but not asked, it is asked again at the next start: %w", err)
}
}
res, err := stepOf(p, in.Step, in.Artifact)
if err != nil {
return seat.RerunAnswer{}, err
}
r := p.Steps[res]
return seat.RerunAnswer{Pipeline: in.Pipeline, Result: &r}, nil
}
// askOf is the ask to put on the serving seat for step s again: the one Place makes for it, under a new id (an ask put twice
// under one id is kept once), saying it is a rerun and by whom.
func (v Verbs) askOf(p seat.Pipeline, s seat.StepResult, caller string, now time.Time) (*Asked, error) {
if v.Starter == nil || v.Starter.Registration == nil || v.Starter.Steps == nil || (v.View == nil && p.Run == "") {
return nil, errors.New("the runner cannot ask a step: it holds no registration or no ask")
}
reg, ok := v.Starter.Registration(p.Module)
if !ok {
return nil, fmt.Errorf("%s has no registration", p.Module)
}
var half Half
if p.Run != "" {
if v.Candidate == nil {
return nil, errors.New("the runner cannot read a run's candidate")
}
var err error
if half, err = v.Candidate(RunGroupPrefix+p.Run, keys.EscapeName(p.Branch), p.Revision); err != nil {
return nil, fmt.Errorf("the candidate %s%s's revision %d is not read, so its step is not asked: %w", RunGroupPrefix, p.Run, p.Revision, err)
}
} else if h, ok := v.View(p.Branch); ok {
half = h
} else {
return nil, fmt.Errorf("the catalog half of %s is not held yet: the step is asked when it is", p.Branch)
}
_, placed := Place(p, reg, half.Entries, now, v.Starter.Name)
base := AskID(startOf(p, now), p.Pipeline, s.Artifact, s.Step)
for _, a := range placed {
if a.ID != base {
continue
}
a.ID = AskID(now, p.Pipeline, s.Artifact, s.Step)
switch b := a.Ask.(type) {
case nodebuildgo.StepAsk:
b.ID = a.ID
if b.Step != nil {
step := *b.Step
step.Rerun, step.By = true, caller
b.Step = &step
}
a.Ask = b
case builds.StepRun:
b.Rerun, b.By = true, caller
a.Ask = b
case wants.StepRun:
b.Rerun, b.By = true, caller
a.Ask = b
}
return &a, nil
}
return nil, fmt.Errorf("the %s step of %s is placed no ask now", s.Step, p.Pipeline)
}
// Run starts a run on request for the caller the bus proved (design 47 G §64; Starter.Run): its pipelines written, its
// run-started said, its steps placed when its candidate's revision is heard.
func (v Verbs) Run(caller string, in seat.RunInput) (seat.RunAnswer, error) {
if v.Starter == nil {
return seat.RunAnswer{}, errors.New("the runner cannot start a run: it holds no starter")
}
return v.Starter.Run(caller, in, NewRunID)
}
// Start starts by hand a delivering pipeline for the head of a watched branch the runner's catalog half holds, recorded in
// the hand-act log first (§306, §394): the pipeline of that branch's source revision and the module, as a take-in would
// start it. A head whose pipeline is written already starts nothing and is refused, naming the pipeline.
func (v Verbs) Start(_ string, in seat.StartInput) (seat.StartAnswer, error) {
if in.Branch == "" || in.Module == "" {
return seat.StartAnswer{}, errors.New("start names the watched branch and the module")
}
if v.Starter == nil || v.View == nil {
return seat.StartAnswer{}, errors.New("the runner cannot start a pipeline: it holds no starter or no catalog half")
}
half, ok := v.View(in.Branch)
if !ok {
return seat.StartAnswer{}, fmt.Errorf("the catalog half of %s is not held yet: nothing was started", in.Branch)
}
e, ok := half.Entries[in.Module]
if !ok || half.Source <= 0 {
return seat.StartAnswer{}, fmt.Errorf("the catalog half of %s holds no entry of %s at a source revision: nothing was started", in.Branch, in.Module)
}
key := Key(in.Branch, half.Source, in.Module)
if err := v.record(seat.VerbStart, "started the pipeline "+key+" by hand", in.Why); err != nil {
return seat.StartAnswer{}, err
}
started, err := v.Starter.Start(Begin{Branch: in.Branch, Source: half.Source, Module: in.Module, Commit: e.Commit, Fp: e.Fp,
Repository: e.Repository, Revision: half.Revision, Entries: half.Entries})
if err != nil {
return seat.StartAnswer{}, err
}
if !started {
return seat.StartAnswer{}, fmt.Errorf("the pipeline %s of the head is started already: a step of it is asked again by rerun", key)
}
return seat.StartAnswer{Pipeline: key}, nil
}
// AskAgain asks a declined approval step once more (§306, §36), recorded in the hand-act log first: the step waits again,
// marked asked again by the caller the bus proved, and is asked at once when the pipeline's every other required step
// passed, under an ask of its own (the earlier ask's decision ended it).
func (v Verbs) AskAgain(caller string, in seat.AskAgainInput) (seat.AskAgainAnswer, error) {
p, i, err := v.change(in.Pipeline, seat.EventStepStarted, func() error {
return v.record(seat.VerbAskAgain, "asked the approval of "+in.Pipeline+" again", in.Why)
}, func(p *seat.Pipeline, now time.Time) (int, error) {
switch p.Outcome {
case seat.PipelineOutcomeCancelled, seat.PipelineOutcomeSuperseded:
return -1, fmt.Errorf("the pipeline %s is %s: its approval is not asked again", p.Pipeline, p.Outcome)
}
i, err := stepOf(*p, seat.StepResultStepApproval, "")
if err != nil {
return -1, err
}
s := &p.Steps[i]
if s.Outcome != seat.StepResultOutcomeDeclined {
return -1, fmt.Errorf("only a declined approval is asked again: the approval of %s is %s", p.Pipeline, s.Outcome)
}
*s = seat.StepResult{Step: s.Step, Artifact: s.Artifact, Status: s.Status, Fingerprint: s.Fingerprint,
Outcome: seat.StepResultOutcomeWaiting, By: caller, Rerun: true, Started: &now}
if p.Outcome != seat.PipelineOutcomeRunning {
p.Outcome, p.Why, p.Ended = seat.PipelineOutcomeRunning, "", nil
}
return i, nil
})
if err != nil {
return seat.AskAgainAnswer{}, err
}
v.Hearer.pin(p)
return seat.AskAgainAnswer{Result: p.Steps[i]}, nil
}