Files
mesh-delivery/modules/mesh-delivery-pipeline/internal/pipeline/verbs.go
T
jschoubben 03b7b6ed24 A-297: the runner's step ask id takes the usual ask id form, so the holders accept it
The runner's step ask id was `step-<24 hex>`; every build seat holder's CheckAskID refuses it (base 36
milliseconds and six hex digits), so no placed step could be accepted. AskID now opens with base 36 of
the pipeline's start time in milliseconds and ends with six hex digits of the sha256 of the pipeline,
the artifact and the step: the same placement makes the same id at every start. A rerun uses its own
time.

Builds: design 47 G A-297, A-232, A-111

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 18:50:29 +01:00

428 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
}
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
}
return seat.AskAgainAnswer{Result: p.Steps[i]}, nil
}