H-A-479 (1) runner: start with modules starts a failed mover again at the head

A module whose pipeline failed at an unchanged entry was never carried again
until its fingerprint moved, since start refused the head whose pipeline
existed. The start verb now takes modules: the named modules whose newest
entry has no passed pipeline are started at the head's revision, at the
take-in's tiers, keyed <branch>.<revision>.again.<n> (n from 1, written on
absence); a module whose newest entry passed, or that the head holds no
entry of, is refused by name, nothing started. Exactly one of module or
modules is given. The new key form is read by every key-form list (the
sweep's, a release's, the mover keys'). The runner seat's form is 8; the
contract is regenerated.

Builds: design 47 H2 H-A-479, H-A-479 addendum (1)
This commit is contained in:
2026-11-22 16:05:27 +01:00
parent b691428ffc
commit 33feb148ce
11 changed files with 315 additions and 23 deletions
@@ -14,13 +14,13 @@ const Seat = "mesh-pipeline-runner"
// Form is the form of the seat's values, events and answers this contract was generated at (design 47 H2 §780):
// a reader of a value of another form says "form N, this reader knows M".
const Form = 7
const Form = 8
// The forms and the digest of the fields this contract was generated from: the generator's compare fails a definition
// whose fields changed while its forms did not (design 47 H2 §780).
const (
generatedForms = "7"
generatedFieldsDigest = "AcceptAnswer=224df0394653 Accepted=d2b011e5090f AskAgainAnswer=224df0394653 CancelAnswer=a0dcc32b3f57 EndAgainAnswer=a0dcc32b3f57 FailedStep=cd7184342136 Fill=7a76c9ceb157 FillingEvent=5bd4df78ed84 FullEvent=5bd4df78ed84 KeptAnswer=dfe0d48bc169 KeptByLevelDigestValue=f06c90f7da7f KeptResult=af5f81f189b7 ListAnswer=284210b3c054 LogEntry=b059967b2ae4 Member=8a103baec01f Mover=5db376275bcf MoverEnded=4b35095f6829 MoverRow=b61f41d131a3 Pipeline=2663792125bf PipelineEnded=523f8fc0fe41 PipelineEndedEvent=cb44007f7173 PipelineEndedPhases=9d1c33ce4cc4 PipelineEndedPhasesBuild=a08d49692a09 PipelineEndedPhasesComposition=a08d49692a09 PipelineEndedPhasesIntegration=a08d49692a09 PipelineEndedPhasesLint=a08d49692a09 PipelineEndedPhasesUnit=a08d49692a09 PipelineEndedPhasesValidate=a08d49692a09 PipelineRow=f58dbdcaf2d4 PipelineStarted=a3d000f095db PipelineStartedEvent=eaa401af4117 PipelinesByBranchRevisionUnfinishedModuleValue=693580eed498 PipelinesByBranchRevisionValue=693580eed498 PipelinesByBranchRunRunValue=693580eed498 PipelinesByBranchSourcePublishedPackageVersionValue=693580eed498 PipelinesByStepsPipelineMoverValue=94de99db7816 PlaceAnswer=a0dcc32b3f57 PlaceUnfinishedAnswer=ed94ced4513a Published=d9af3024dacc QueueByQueueNextValue=765a2918a728 QueueByRunningPipelineValue=ed94ced4513a QueueByWaitingSequenceValue=99605298ae13 RePinnedEvent=92fd04bfa6d3 RerunAnswer=9b7efd0df344 ReviewAnswer=f397b8965179 RoomEvent=5bd4df78ed84 RunAnswer=96bd45aa2e62 RunStarted=b280617410c3 RunStartedEvent=0767a9358fa3 Shared=c981cf6aa860 SharedAskedBy=c9b30cc4d0d0 ShowAnswer=48b8cecc529a StandsAnswer=0afa3693bf3b StartAnswer=ed94ced4513a StepEndedEvent=799020642c19 StepEvent=64f18c40ed5d StepLogByPipelineValue=ffdde090a101 StepResult=0dac0e15d017 StepStartedEvent=799020642c19 TestCounts=9c1332427159 TestRun=ca5a87f3b6b8 TestRunPackage=a7d30558470d TestRunReader=c9b30cc4d0d0 TestRunsAnswer=7ab81a45ca33 TestRunsDropAnswer=8ee70b35469d ToolchainUsed=43b6d42376fb Wait=21e4ee7a3ef1 WaitEndedEvent=2bf6d38041c0 WaitHeldEvent=2bf6d38041c0 Waiting=ed94ced4513a WhyCarriedAnswer=8e2fcea6479f Widening=e2790a307466"
generatedForms = "8"
generatedFieldsDigest = "AcceptAnswer=224df0394653 Accepted=d2b011e5090f AskAgainAnswer=224df0394653 CancelAnswer=a0dcc32b3f57 EndAgainAnswer=a0dcc32b3f57 FailedStep=cd7184342136 Fill=7a76c9ceb157 FillingEvent=5bd4df78ed84 FullEvent=5bd4df78ed84 KeptAnswer=dfe0d48bc169 KeptByLevelDigestValue=f06c90f7da7f KeptResult=af5f81f189b7 ListAnswer=284210b3c054 LogEntry=b059967b2ae4 Member=8a103baec01f Mover=5db376275bcf MoverEnded=4b35095f6829 MoverRow=b61f41d131a3 Pipeline=2663792125bf PipelineEnded=523f8fc0fe41 PipelineEndedEvent=cb44007f7173 PipelineEndedPhases=9d1c33ce4cc4 PipelineEndedPhasesBuild=a08d49692a09 PipelineEndedPhasesComposition=a08d49692a09 PipelineEndedPhasesIntegration=a08d49692a09 PipelineEndedPhasesLint=a08d49692a09 PipelineEndedPhasesUnit=a08d49692a09 PipelineEndedPhasesValidate=a08d49692a09 PipelineRow=f58dbdcaf2d4 PipelineStarted=a3d000f095db PipelineStartedEvent=eaa401af4117 PipelinesByBranchRevisionAgainNValue=693580eed498 PipelinesByBranchRevisionUnfinishedModuleValue=693580eed498 PipelinesByBranchRevisionValue=693580eed498 PipelinesByBranchRunRunValue=693580eed498 PipelinesByBranchSourcePublishedPackageVersionValue=693580eed498 PipelinesByStepsPipelineMoverValue=94de99db7816 PlaceAnswer=a0dcc32b3f57 PlaceUnfinishedAnswer=ed94ced4513a Published=d9af3024dacc QueueByQueueNextValue=765a2918a728 QueueByRunningPipelineValue=ed94ced4513a QueueByWaitingSequenceValue=99605298ae13 RePinnedEvent=92fd04bfa6d3 RerunAnswer=9b7efd0df344 ReviewAnswer=f397b8965179 RoomEvent=5bd4df78ed84 RunAnswer=96bd45aa2e62 RunStarted=b280617410c3 RunStartedEvent=0767a9358fa3 Shared=c981cf6aa860 SharedAskedBy=c9b30cc4d0d0 ShowAnswer=48b8cecc529a StandsAnswer=0afa3693bf3b StartAnswer=ed94ced4513a StepEndedEvent=799020642c19 StepEvent=64f18c40ed5d StepLogByPipelineValue=ffdde090a101 StepResult=0dac0e15d017 StepStartedEvent=799020642c19 TestCounts=9c1332427159 TestRun=ca5a87f3b6b8 TestRunPackage=a7d30558470d TestRunReader=c9b30cc4d0d0 TestRunsAnswer=7ab81a45ca33 TestRunsDropAnswer=8ee70b35469d ToolchainUsed=43b6d42376fb Wait=21e4ee7a3ef1 WaitEndedEvent=2bf6d38041c0 WaitHeldEvent=2bf6d38041c0 Waiting=ed94ced4513a WhyCarriedAnswer=8e2fcea6479f Widening=e2790a307466"
)
const (
@@ -69,7 +69,7 @@ func VerbDescription(verb string) string {
case VerbRun:
return "The run on request of one or more members, each a module at a named commit, through their pipelines; delivers nothing, replacing the checker's try (ADR 0666 section 18). Says run-started."
case VerbStart:
return "A delivering pipeline for a watched branch's head, by hand; written in the hand-act log."
return "A delivering pipeline for a watched branch's head, by hand; written in the hand-act log. With modules, a pipeline at the head keyed <branch>.<revision>.again.<n> carrying the named modules whose newest entry has no passed pipeline, at the take-in's tiers; a module whose newest entry passed is refused by name. Exactly one of module or modules (design 47 H2 H-A-479)."
case VerbShow:
return "One pipeline: naming a mover, its steps alone; with no mover, each mover's row (its module, outcome and failed step), never every step of every mover, or the steps of any mover the step and state filters hold; and its step log, with the stores' fill (design 47 H2 §789, H-A-376). Reads only."
case VerbList:
@@ -354,6 +354,44 @@ func DecodePipelinesByBranchRevisionUnfinishedModuleValue(raw []byte) (Pipelines
return v, formRead(raw), nil
}
// PipelinesByBranchRevisionAgainNKey is the key of one value of the state pipelines under the form "<branch>.<revision>.again.<n>".
func PipelinesByBranchRevisionAgainNKey(branch, revision, n string) string {
return branch + "." + revision + ".again." + n
}
// ParsePipelinesByBranchRevisionAgainNKey reads the parts of a key of the form "<branch>.<revision>.again.<n>", in the order of the form; the last result is false for a key of another form.
func ParsePipelinesByBranchRevisionAgainNKey(key string) (string, string, string, bool) {
rest := key
v0, after0, found0 := strings.Cut(rest, ".")
if !found0 || v0 == "" {
return "", "", "", false
}
rest = after0
v2, after2, found2 := strings.Cut(rest, ".again.")
if !found2 || v2 == "" {
return "", "", "", false
}
rest = after2
if rest == "" {
return "", "", "", false
}
v4 := rest
rest = ""
if rest != "" {
return "", "", "", false
}
return v0, v2, v4, true
}
// DecodePipelinesByBranchRevisionAgainNValue reads one value of the state pipelines under the form "<branch>.<revision>.again.<n>" as another part wrote it: a field PipelinesByBranchRevisionAgainNValue does not know is left unread, never refused; the form read is answered, 1 when absent (design 47 H2 §780).
func DecodePipelinesByBranchRevisionAgainNValue(raw []byte) (PipelinesByBranchRevisionAgainNValue, int, error) {
var v PipelinesByBranchRevisionAgainNValue
if err := json.Unmarshal(raw, &v); err != nil {
return v, 0, err
}
return v, formRead(raw), nil
}
// PipelinesByStepsPipelineMoverKey is the key of one value of the state pipelines under the form "steps.<pipeline>.<mover>".
func PipelinesByStepsPipelineMoverKey(pipeline, mover string) string {
return "steps." + pipeline + "." + mover
@@ -1244,7 +1282,10 @@ type RunAnswer struct {
// StartInput is what start takes.
type StartInput struct {
Branch string `json:"branch"`
Module string `json:"module"`
// the one mover of the head's pipeline <branch>.<revision>; absent when modules is given
Module string `json:"module,omitempty"`
// the modules started again at the head, each whose newest entry has no passed pipeline (a failed, cut or superseded one); absent when module is given (design 47 H2 H-A-479)
Modules []string `json:"modules,omitempty"`
// why, written with the caller the runtime proves in the hand-act log
Why string `json:"why"`
}
@@ -1637,6 +1678,9 @@ type PipelinesByBranchRunRunValue = Pipeline
// PipelinesByBranchRevisionUnfinishedModuleValue is one value of the state pipelines under the key <branch>.<revision>.unfinished.<module>.
type PipelinesByBranchRevisionUnfinishedModuleValue = Pipeline
// PipelinesByBranchRevisionAgainNValue is one value of the state pipelines under the key <branch>.<revision>.again.<n>.
type PipelinesByBranchRevisionAgainNValue = Pipeline
// PipelinesByStepsPipelineMoverValue is one value of the state pipelines under the key steps.<pipeline>.<mover>.
type PipelinesByStepsPipelineMoverValue struct {
// is the form of what this value carries, left out while it is 1 (design 47 H2 §780).
@@ -50,12 +50,20 @@
},
{
"name": "start",
"description": "A delivering pipeline for a watched branch's head, by hand; written in the hand-act log.",
"description": "A delivering pipeline for a watched branch's head, by hand; written in the hand-act log. With modules, a pipeline at the head keyed <branch>.<revision>.again.<n> carrying the named modules whose newest entry has no passed pipeline, at the take-in's tiers; a module whose newest entry passed is refused by name. Exactly one of module or modules (design 47 H2 H-A-479).",
"input": {
"type": "object",
"properties": {
"module": {
"type": "string"
"type": "string",
"description": "the one mover of the head's pipeline <branch>.<revision>; absent when modules is given"
},
"modules": {
"type": "array",
"items": {
"type": "string"
},
"description": "the modules started again at the head, each whose newest entry has no passed pipeline (a failed, cut or superseded one); absent when module is given (design 47 H2 H-A-479)"
},
"branch": {
"type": "string"
@@ -66,7 +74,6 @@
}
},
"required": [
"module",
"branch",
"why"
]
@@ -910,6 +917,13 @@
},
"description": "a pipeline of its own of one mover kept in the runner's state unfinished, put in it by place-unfinished; the revision the unfinished entry names (design 47 H2 §86, H-A-398)"
},
{
"key": "<branch>.<revision>.again.<n>",
"value": {
"$ref": "#/defs/Pipeline"
},
"description": "a pipeline started again at the head by start with modules, its movers the named modules whose newest entry has no passed pipeline; n from 1, taken by writing on absence (design 47 H2 H-A-479)"
},
{
"key": "steps.<pipeline>.<mover>",
"value": {
@@ -2353,5 +2367,5 @@
]
}
},
"form": 7
"form": 8
}
@@ -121,6 +121,12 @@ export declare function pipelinesByBranchRevisionUnfinishedModuleKey(branch: str
/** The parts of a key of the form "<branch>.<revision>.unfinished.<module>", or undefined for a key of another form. */
export declare function parsePipelinesByBranchRevisionUnfinishedModuleKey(_key: string): { branch: string; revision: string; module: string } | undefined;
/** The key of one value of the state pipelines under the form "<branch>.<revision>.again.<n>". */
export declare function pipelinesByBranchRevisionAgainNKey(branch: string, revision: string, n: string): string;
/** The parts of a key of the form "<branch>.<revision>.again.<n>", or undefined for a key of another form. */
export declare function parsePipelinesByBranchRevisionAgainNKey(_key: string): { branch: string; revision: string; n: string } | undefined;
/** The key of one value of the state pipelines under the form "steps.<pipeline>.<mover>". */
export declare function pipelinesByStepsPipelineMoverKey(pipeline: string, mover: string): string;
@@ -699,7 +705,10 @@ export interface RunAnswer {
/** is what start takes. */
export interface StartInput {
"branch": string;
"module": string;
/** the one mover of the head's pipeline <branch>.<revision>; absent when modules is given */
"module"?: string;
/** the modules started again at the head, each whose newest entry has no passed pipeline (a failed, cut or superseded one); absent when module is given (design 47 H2 H-A-479) */
"modules"?: string[];
/** why, written with the caller the runtime proves in the hand-act log */
"why": string;
}
@@ -1031,6 +1040,9 @@ export type PipelinesByBranchRunRunValue = Pipeline;
/** is one value of the state pipelines under the key <branch>.<revision>.unfinished.<module>. */
export type PipelinesByBranchRevisionUnfinishedModuleValue = Pipeline;
/** is one value of the state pipelines under the key <branch>.<revision>.again.<n>. */
export type PipelinesByBranchRevisionAgainNValue = Pipeline;
/** is one value of the state pipelines under the key steps.<pipeline>.<mover>. */
export interface PipelinesByStepsPipelineMoverValue {
/** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */
@@ -199,6 +199,29 @@ export function parsePipelinesByBranchRevisionUnfinishedModuleKey(_key) {
return { branch, revision, module };
}
/** The key of one value of the state pipelines under the form "<branch>.<revision>.again.<n>". */
export function pipelinesByBranchRevisionAgainNKey(branch, revision, n) {
return branch + "." + revision + ".again." + n;
}
/** The parts of a key of the form "<branch>.<revision>.again.<n>", or undefined for a key of another form. */
export function parsePipelinesByBranchRevisionAgainNKey(_key) {
let _rest = _key;
const _at0 = _rest.indexOf(".");
if (_at0 <= 0) return undefined;
const branch = _rest.slice(0, _at0);
_rest = _rest.slice(_at0 + 1);
const _at2 = _rest.indexOf(".again.");
if (_at2 <= 0) return undefined;
const revision = _rest.slice(0, _at2);
_rest = _rest.slice(_at2 + 7);
if (_rest === "") return undefined;
const n = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { branch, revision, n };
}
/** The key of one value of the state pipelines under the form "steps.<pipeline>.<mover>". */
export function pipelinesByStepsPipelineMoverKey(pipeline, mover) {
return "steps." + pipeline + "." + mover;
@@ -19,11 +19,11 @@ func VerbTools(ask func(key string, body any) (json.RawMessage, error)) []stdio.
}
return []stdio.Tool{
verbTool[seat.StartInput](ask, "start", seat.VerbStart,
"Start by hand the delivering pipeline of the head of a watched branch for a module, by the seat verb start: the branch, the module and why. A head whose pipeline is written already is refused by the verb, naming it.",
obj([]string{"branch", "module", "why"}, map[string]any{"branch": str, "module": str, "why": str}),
"Start by hand the delivering pipeline of the head of a watched branch for a module, by the seat verb start: the branch, the module and why. A head whose pipeline is written already is refused by the verb, naming it. With modules instead of module, the named modules whose newest entry has no passed pipeline (a failed, cut or superseded one) are started again at the head, keyed <branch>.<revision>.again.<n>; a module whose newest entry passed is refused by name (design 47 H2 H-A-479).",
obj([]string{"branch", "why"}, map[string]any{"branch": str, "module": str, "modules": map[string]any{"type": "array", "items": str}, "why": str}),
func(in seat.StartInput) string {
if in.Branch == "" || in.Module == "" {
return "start names the watched branch and the module"
if in.Branch == "" || (in.Module == "") == (len(in.Modules) == 0) {
return "start names the watched branch and exactly one of the module or the modules"
}
return whyOf(in.Why)
}),
@@ -18,7 +18,11 @@ func TestVerbTools(t *testing.T) {
{"start", "runner_start", "seat:mesh-pipeline-runner.start", "", map[string]any{"branch": "main", "module": "i3", "why": "cancelled"},
seat.StartInput{Branch: "main", Module: "i3", Why: "cancelled"}},
{"start no why", "runner_start", "", "names why", map[string]any{"branch": "main", "module": "i3"}, nil},
{"start no module", "runner_start", "", "branch and the module", map[string]any{"branch": "main", "why": "x"}, nil},
{"start no module", "runner_start", "", "exactly one of the module or the modules", map[string]any{"branch": "main", "why": "x"}, nil},
// H-A-479: modules start the named modules again at the head; both together are refused.
{"start modules", "runner_start", "seat:mesh-pipeline-runner.start", "", map[string]any{"branch": "main", "modules": []any{"i3", "lib"}, "why": "failed"},
seat.StartInput{Branch: "main", Modules: []string{"i3", "lib"}, Why: "failed"}},
{"start module and modules", "runner_start", "", "exactly one of the module or the modules", map[string]any{"branch": "main", "module": "i3", "modules": []any{"lib"}, "why": "x"}, nil},
{"run", "runner_run", "seat:mesh-pipeline-runner.run", "", map[string]any{"members": []any{map[string]any{}}, "why": "x"},
seat.RunInput{Members: []seat.Member{{}}, Why: "x"}},
{"run no members", "runner_run", "", "members", map[string]any{}, nil},
@@ -29,8 +29,8 @@ func StepsKey(pipeline, mover string) string {
func stepsPrefix(pipeline string) string { return StepsKey(pipeline, "") }
// IsStepsKey says whether a key of the state pipelines is a mover's steps rather than a pipeline's record: `steps.` and a
// pipeline key of a take-in's (4 parts), a run's (5 parts, its third `run`), an unfinished mover's own (6 parts, its fourth
// `unfinished`, H-A-398) or a publish's (7 parts) and one mover.
// pipeline key of a take-in's (4 parts), a run's (5 parts, its third `run`), an unfinished mover's own or one started again at
// the head (6 parts, its fourth `unfinished`, H-A-398, or `again`, H-A-479) or a publish's (7 parts) and one mover.
func IsStepsKey(key string) bool {
parts := strings.Split(key, ".")
if parts[0] != "steps" {
@@ -42,7 +42,7 @@ func IsStepsKey(key string) bool {
case 5:
return parts[2] == runToken
case 6:
return parts[3] == unfinishedToken
return parts[3] == unfinishedToken || parts[3] == againToken
}
return false
}
@@ -25,7 +25,7 @@ func (h *Hearer) Released(ev catalog.VersionReleasedEvent, branch string) (int,
// A pipeline is keyed by its revision (H-A-213 (4)), so the pipelines of a source are those naming it, of either key
// form a source's pipelines were kept under.
var pkeys []string
for _, f := range []string{b + ".*", b + ".*.published.*.*", b + ".*." + unfinishedToken + ".*"} {
for _, f := range []string{b + ".*", b + ".*.published.*.*", b + ".*." + unfinishedToken + ".*", b + ".*." + againToken + ".*"} {
k, err := h.Store.Keys(f)
if err != nil {
return 0, fmt.Errorf("the pipelines of source %d are not listed: %w", ev.Source, err)
@@ -69,8 +69,19 @@ func keyRevision(b Begin) int64 {
}
// keyForms are the filters of every key form of the state pipelines: a revision's, a run's, a publish's kept from before
// a release revision started one pipeline (H-A-213 (2)), and an unfinished mover's pipeline of its own (H-A-398).
var keyForms = []string{"*.*", "*." + runToken + ".*", "*.*.published.*.*", "*.*." + unfinishedToken + ".*"}
// a release revision started one pipeline (H-A-213 (2)), an unfinished mover's pipeline of its own (H-A-398), and a pipeline
// started again at the head (H-A-479).
var keyForms = []string{"*.*", "*." + runToken + ".*", "*.*.published.*.*", "*.*." + unfinishedToken + ".*", "*.*." + againToken + ".*"}
// againToken is the third part of the key of a pipeline started again at the head by start with modules,
// `<branch>.<revision>.again.<n>` (design 47 H2 H-A-479 addendum (1)).
const againToken = "again"
// AgainPipelineKey is the key of the n-th pipeline started again at revision of branch, `<branch>.<revision>.again.<n>`
// (H-A-479 addendum (1)).
func AgainPipelineKey(branch string, revision int64, n int) string {
return seat.PipelinesByBranchRevisionAgainNKey(keys.EscapeName(branch), strconv.FormatInt(revision, 10), strconv.Itoa(n))
}
// AllKeys are every pipeline's key, of each key form (§746, §747; H-A-83).
func AllKeys(store interface {
@@ -4,6 +4,7 @@ import (
"errors"
"fmt"
"slices"
"strconv"
"strings"
"time"
@@ -649,10 +650,17 @@ func (v Verbs) Run(caller string, in seat.RunInput) (seat.RunAnswer, error) {
// 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.
// start it. A head whose pipeline is written already starts nothing and is refused, naming the pipeline. With modules it
// starts the named modules again at the head instead (startAgain, H-A-479); exactly one of module or modules is given.
func (v Verbs) Start(_ string, in seat.StartInput) (seat.StartAnswer, error) {
if in.Module != "" && len(in.Modules) > 0 {
return seat.StartAnswer{}, errors.New("start names the module or the modules, not both: nothing was started")
}
if in.Branch != "" && len(in.Modules) > 0 {
return v.startAgain(in)
}
if in.Branch == "" || in.Module == "" {
return seat.StartAnswer{}, errors.New("start names the watched branch and the module")
return seat.StartAnswer{}, errors.New("start names the watched branch and the module or the modules")
}
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")
@@ -681,6 +689,112 @@ func (v Verbs) Start(_ string, in seat.StartInput) (seat.StartAnswer, error) {
return seat.StartAnswer{Pipeline: key}, nil
}
// againTries bounds how many next numbers a start again tries when another start took the one it read (H-A-479).
const againTries = 10
// startAgain starts by hand, recorded in the hand-act log first, a pipeline at the head of a watched branch carrying the
// named modules whose newest entry, the head's, has no passed pipeline (a failed, cut or superseded one), with the head's
// revision as its candidate and the take-in's tiers (design 47 H2 H-A-479): keyed `<branch>.<revision>.again.<n>`, n from 1,
// taken by writing on absence (addendum (1)). Its pipeline-started pins the head's revision as a take-in's does, and its
// versions are reserved at its build steps as a take-in's are. A module the head holds no entry of, or whose newest entry
// passed in a pipeline, is refused by name, nothing started.
func (v Verbs) startAgain(in seat.StartInput) (seat.StartAnswer, error) {
if v.Starter == nil || v.View == nil || v.Hearer == nil || v.Hearer.Store == nil {
return seat.StartAnswer{}, errors.New("the runner cannot start a pipeline again: it holds no starter, no catalog half or no state pipelines")
}
half, ok := v.View(in.Branch)
if !ok || half.Source <= 0 {
return seat.StartAnswer{}, fmt.Errorf("the catalog half of %s is not held at a source revision yet: nothing was started", in.Branch)
}
movers := make([]seat.Mover, 0, len(in.Modules))
var absent []string
for _, m := range in.Modules {
e, ok := half.Entries[m]
if !ok {
absent = append(absent, m)
continue
}
if slices.ContainsFunc(movers, func(x seat.Mover) bool { return x.Module == m }) {
continue
}
movers = append(movers, seat.Mover{Module: m, Commit: e.Commit, Fingerprint: e.Fp, Repository: e.Repository})
}
if len(absent) > 0 {
return seat.StartAnswer{}, fmt.Errorf("the head of %s (revision %d) holds no entry of %s: nothing was started", in.Branch, half.Revision, strings.Join(absent, ", "))
}
passed, err := v.passedEntries(in.Branch, movers)
if err != nil {
return seat.StartAnswer{}, err
}
if len(passed) > 0 {
return seat.StartAnswer{}, fmt.Errorf("the newest entry of %s passed already: nothing was started", strings.Join(passed, ", "))
}
movers = Tiers(movers, half.Entries, v.Starter.logf)
names := make([]string, 0, len(movers))
for _, m := range movers {
names = append(names, m.Module)
}
prefix := AgainPipelineKey(in.Branch, half.Revision, 0)
prefix = prefix[:len(prefix)-1]
held, err := v.Hearer.Store.Keys(prefix + "*")
if err != nil {
return seat.StartAnswer{}, fmt.Errorf("the pipelines started again at revision %d of %s are not listed: nothing was started: %w", half.Revision, in.Branch, err)
}
n := 1
for _, k := range held {
if i, err := strconv.Atoi(strings.TrimPrefix(k, prefix)); err == nil && i >= n {
n = i + 1
}
}
if err := v.record(seat.VerbStart, fmt.Sprintf("started %s again at the head of %s by hand", strings.Join(names, ", "), in.Branch), in.Why); err != nil {
return seat.StartAnswer{}, err
}
for range againTries {
key := AgainPipelineKey(in.Branch, half.Revision, n)
started, err := v.Starter.Start(Begin{Branch: in.Branch, Source: half.Source, Revision: half.Revision, Entries: half.Entries,
Key: key, Movers: movers})
if err != nil {
return seat.StartAnswer{}, err
}
if started {
v.Starter.logf("%s starts %s again at the head by hand (H-A-479)", key, strings.Join(names, ", "))
return seat.StartAnswer{Pipeline: key}, nil
}
n++
}
return seat.StartAnswer{}, fmt.Errorf("no key %s<n> was free in %d tries: nothing was started", prefix, againTries)
}
// passedEntries are the movers whose module, at the mover's fingerprint, a passed delivering pipeline of branch carries and
// did not leave (H-A-479: a newest entry that passed is not started again).
func (v Verbs) passedEntries(branch string, movers []seat.Mover) ([]string, error) {
pkeys, err := branchKeys(v.Hearer.Store, branch)
if err != nil {
return nil, fmt.Errorf("the pipelines of %s are not listed, so nothing was started: %w", branch, err)
}
var passed []string
seen := map[string]bool{}
for _, key := range pkeys {
p, _, err := v.Hearer.Store.Get(key)
if err != nil {
return nil, fmt.Errorf("the pipeline %s is not read, so nothing was started: %w", key, err)
}
if p.Run != "" || p.Outcome != seat.PipelineOutcomePassed {
continue
}
for _, m := range movers {
if seen[m.Module] || slices.Contains(p.Superseded, m.Module) {
continue
}
if pm, ok := MoverOf(p, m.Module); ok && pm.Fingerprint == m.Fingerprint {
seen[m.Module] = true
passed = append(passed, m.Module+" (in "+key+")")
}
}
}
return passed, 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).
@@ -1,6 +1,7 @@
package pipeline
import (
"encoding/json"
"errors"
"strings"
"testing"
@@ -423,3 +424,72 @@ func TestAValidateRerunMovesEveryMoversValidateAndReopensItsCompositions(t *test
}
}
}
// H-A-479: start with modules starts a pipeline at the head keyed <branch>.<revision>.again.<n> carrying the named modules
// whose newest entry has no passed pipeline, at the take-in's tiers; a module whose newest entry passed is refused by name,
// nothing started; exactly one of module or modules is given; a second start takes the next n.
func TestStartWithModulesStartsAFailedMoverAgainAtTheHead(t *testing.T) {
v, store, _, _, acts, _ := verbsFixture()
made := created{}
var started []seat.PipelineStarted
v.Starter.Pipelines = made
v.Starter.Say = func(_ string, body any) error {
if ps, ok := body.(seat.PipelineStarted); ok {
started = append(started, ps)
}
return nil
}
_, entries := placeFixture()
app := entries["app"]
app.Fp, app.Commit, app.Repository = "src2:aa", "c1", "o/app"
entries["app"] = app
entries["lib"] = catalog.CatalogEntry{Module: "lib", Fp: "src2:bb", Commit: "c2", Repository: "o/lib"}
v.View = func(string) (Half, bool) { return Half{Source: 7, Revision: 9, Entries: entries}, true }
// The fixture's main.5 moves app at src2:aa and failed; lib's newest entry passed in main.8.
e := store[pkey]
e.p.Outcome = seat.PipelineOutcomeFailed
store[pkey] = e
store["main.8"] = struct {
p seat.Pipeline
rev uint64
}{seat.Pipeline{Pipeline: "main.8", Branch: "main", Source: 6, Revision: 8, Outcome: seat.PipelineOutcomePassed,
Movers: []seat.Mover{{Module: "lib", Fingerprint: "src2:bb"}, {Module: "app", Fingerprint: "src2:aa"}}, Superseded: []string{"app"}}, 1}
if _, err := v.Start("operator", seat.StartInput{Branch: "main", Module: "app", Modules: []string{"app"}, Why: "x"}); err == nil {
t.Error("a start naming both module and modules was taken")
}
if _, err := v.Start("operator", seat.StartInput{Branch: "main", Modules: []string{"app", "lib"}, Why: "x"}); err == nil || !strings.Contains(err.Error(), "lib") {
t.Errorf("a start naming lib, whose newest entry passed, = %v; want refused naming lib", err)
}
if len(made) != 0 {
t.Fatalf("a refused start wrote %d pipelines", len(made))
}
a, err := v.Start("operator", seat.StartInput{Branch: "main", Modules: []string{"app"}, Why: "its pipeline failed at an unchanged entry"})
if err != nil || a.Pipeline != "main.9.again.1" || made["main.9.again.1"] == nil {
t.Fatalf("start with modules = %+v, %v; written %v", a, err, len(made))
}
var p seat.Pipeline
if err := json.Unmarshal(made["main.9.again.1"], &p); err != nil {
t.Fatal(err)
}
if p.Revision != 9 || p.Source != 7 || len(p.Movers) != 1 || p.Movers[0].Module != "app" || p.Movers[0].Fingerprint != "src2:aa" || p.Movers[0].Tier != 1 {
t.Errorf("the pipeline = %+v, want app at src2:aa, tier 1, at revision 9 of source 7", p)
}
if len(started) != 1 || started[0].Pipeline != "main.9.again.1" || started[0].Revision != 9 {
t.Errorf("pipeline-started = %+v, want main.9.again.1 at revision 9 (its revision pinned)", started)
}
// The next start at the same head takes the next n.
store["main.9.again.1"] = struct {
p seat.Pipeline
rev uint64
}{p, 1}
if a, err := v.Start("operator", seat.StartInput{Branch: "main", Modules: []string{"app"}, Why: "again"}); err != nil || a.Pipeline != "main.9.again.2" {
t.Errorf("a second start with modules = %+v, %v; want main.9.again.2", a, err)
}
if len(*acts) != 2 {
t.Errorf("hand acts %v, want the two starts recorded", *acts)
}
if !IsStepsKey(StepsKey("main.9.again.1", "app")) {
t.Error("a mover key of an again pipeline is not read as a mover's steps")
}
}