diff --git a/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go b/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go index 926bf85e..ce60aa65 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go @@ -26,6 +26,7 @@ const ( VerbRerun = "rerun" VerbAccept = "accept" VerbCancel = "cancel" + VerbEndAgain = "end-again" VerbPlace = "place" VerbAskAgain = "ask-again" VerbTestRuns = "test-runs" @@ -47,7 +48,7 @@ const ( // Verbs is every verb the seat serves, in its definition's order: a new copy each call. func Verbs() []string { - return []string{VerbRun, VerbStart, VerbShow, VerbList, VerbStands, VerbWhyCarried, VerbKept, VerbReview, VerbRerun, VerbAccept, VerbCancel, VerbPlace, VerbAskAgain, VerbTestRuns, VerbTestRunsDrop} + return []string{VerbRun, VerbStart, VerbShow, VerbList, VerbStands, VerbWhyCarried, VerbKept, VerbReview, VerbRerun, VerbAccept, VerbCancel, VerbEndAgain, VerbPlace, VerbAskAgain, VerbTestRuns, VerbTestRunsDrop} } // Events is every event published on the seat's subject: a new copy each call. @@ -1195,6 +1196,19 @@ type CancelAnswer struct { Pipeline Pipeline `json:"pipeline"` } +// EndAgainInput is what end-again takes. +type EndAgainInput struct { + // the pipeline's key + Pipeline string `json:"pipeline"` + // why, written with the caller the runtime proves in the hand-act log + Why string `json:"why"` +} + +// EndAgainAnswer is what end-again answers. +type EndAgainAnswer struct { + Pipeline Pipeline `json:"pipeline"` +} + // PlaceInput is what place takes. type PlaceInput struct { // the pipeline's key diff --git a/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract_test.go b/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract_test.go index bc6af73a..23b59e9c 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract_test.go +++ b/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract_test.go @@ -119,6 +119,8 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v TestRunsDropAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "place asks a waiting pipeline ahead of its turn, with why", subject: "", given: "{\"pipeline\":\"main.3590\",\"why\":\"the operator wants the fix out first\"}", wire: "{\"pipeline\":\"main.3590\",\"why\":\"the operator wants the fix out first\"}", decode: func(b []byte) (any, error) { var v PlaceInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "end-again asks a running pipeline's end judged once more, with why", subject: "", given: "{\"pipeline\":\"main.20\",\"why\":\"a mover waits on its registration and another failed\"}", wire: "{\"pipeline\":\"main.20\",\"why\":\"a mover waits on its registration and another failed\"}", + decode: func(b []byte) (any, error) { var v EndAgainInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } for _, c := range cases { v, err := c.decode([]byte(c.given)) diff --git a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/verbs.json b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/verbs.json index a056bb02..f966db09 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/verbs.json +++ b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/verbs.json @@ -336,5 +336,13 @@ "pipeline": "main.3590", "why": "the operator wants the fix out first" } + }, + { + "name": "end-again asks a running pipeline's end judged once more, with why", + "of": "verb:end-again.input", + "given": { + "pipeline": "main.20", + "why": "a mover waits on its registration and another failed" + } } ] diff --git a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json index 1e35b5a9..7a5c3607 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json +++ b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json @@ -474,6 +474,39 @@ }, "class": "act" }, + { + "name": "end-again", + "description": "A running pipeline's end judged once more, as at a step's end: it ends when it can, failed as soon as it can no longer pass (design 47 H §746, H-A-163, H-A-164). Written in the hand-act log.", + "input": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key" + }, + "why": { + "type": "string", + "description": "why, written with the caller the runtime proves in the hand-act log" + } + }, + "required": [ + "pipeline", + "why" + ] + }, + "answer": { + "type": "object", + "properties": { + "pipeline": { + "$ref": "#/defs/Pipeline" + } + }, + "required": [ + "pipeline" + ] + }, + "class": "act" + }, { "name": "place", "description": "A waiting pipeline placed ahead of its turn, its steps asked now; written in the hand-act log (design 47 H §748, H-A-53).", diff --git a/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts index 03e13f17..4fb293a0 100644 --- a/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts @@ -16,6 +16,7 @@ export declare const verbs: { readonly rerun: "rerun"; readonly accept: "accept"; readonly cancel: "cancel"; + readonly endAgain: "end-again"; readonly place: "place"; readonly askAgain: "ask-again"; readonly testRuns: "test-runs"; @@ -683,6 +684,19 @@ export interface CancelAnswer { "pipeline": Pipeline; } +/** is what end-again takes. */ +export interface EndAgainInput { + /** the pipeline's key */ + "pipeline": string; + /** why, written with the caller the runtime proves in the hand-act log */ + "why": string; +} + +/** is what end-again answers. */ +export interface EndAgainAnswer { + "pipeline": Pipeline; +} + /** is what place takes. */ export interface PlaceInput { /** the pipeline's key */ diff --git a/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.js b/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.js index 721b6839..32282d84 100644 --- a/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.js +++ b/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.js @@ -16,6 +16,7 @@ export const verbs = { rerun: "rerun", accept: "accept", cancel: "cancel", + endAgain: "end-again", place: "place", askAgain: "ask-again", testRuns: "test-runs", diff --git a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main_test.go b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main_test.go index 2d942ecb..95bb4bda 100644 --- a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main_test.go +++ b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main_test.go @@ -42,7 +42,7 @@ func TestTools(t *testing.T) { for _, tl := range UnloggedTools(stdio.State("pipelines"), stdio.Log("step-log"), nil, nil) { names = append(names, tl.Name) } - want := "mesh-pipeline-runner.show mesh-pipeline-runner.list mesh-pipeline-runner.stands mesh-pipeline-runner.why-carried mesh-pipeline-runner.kept runner_first_views runner_first_view_again runner_cancel runner_rerun runner_start runner_run runner_accept runner_place runner_ask_again runner_health runner_waiting runner_unlogged runner_unlogged_append" + want := "mesh-pipeline-runner.show mesh-pipeline-runner.list mesh-pipeline-runner.stands mesh-pipeline-runner.why-carried mesh-pipeline-runner.kept runner_first_views runner_first_view_again runner_cancel runner_rerun runner_start runner_run runner_accept runner_place runner_end_again runner_ask_again runner_health runner_waiting runner_unlogged runner_unlogged_append" if got := strings.Join(names, " "); got != want { t.Errorf("tools %q, want %q", got, want) } diff --git a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools.go b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools.go index e3711cc4..7b887bf6 100644 --- a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools.go +++ b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools.go @@ -54,6 +54,15 @@ func VerbTools(ask func(key string, body any) (json.RawMessage, error)) []stdio. } return whyOf(in.Why) }), + verbTool[seat.EndAgainInput](ask, "end_again", seat.VerbEndAgain, + "Judge a running pipeline's end once more by the seat verb end-again (design 47 H H-A-163, H-A-164): it ends as at a step's end, failed as soon as it can no longer pass (a mover with no registration named), and says pipeline-ended; one that still cannot end is answered running. The pipeline's key and why; written in the hand-act log. A pipeline not running is refused by the verb.", + obj([]string{"pipeline", "why"}, map[string]any{"pipeline": str, "why": str}), + func(in seat.EndAgainInput) string { + if in.Pipeline == "" { + return "end-again names the pipeline" + } + return whyOf(in.Why) + }), verbTool[seat.AskAgainInput](ask, "ask_again", seat.VerbAskAgain, "Ask a declined approval step of a pipeline once more by the seat verb ask-again: the pipeline's key, the mover's module (needed when the pipeline moves several) and why.", obj([]string{"pipeline", "why"}, map[string]any{"pipeline": str, "module": str, "why": str}), diff --git a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools_test.go b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools_test.go index ff163acd..40f7558e 100644 --- a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools_test.go +++ b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/verbtools_test.go @@ -32,6 +32,10 @@ func TestVerbTools(t *testing.T) { {"place", "runner_place", "seat:mesh-pipeline-runner.place", "", map[string]any{"pipeline": "main.6", "why": "urgent"}, seat.PlaceInput{Pipeline: "main.6", Why: "urgent"}}, {"place no why", "runner_place", "", "names why", map[string]any{"pipeline": "main.6"}, nil}, + // H-A-164: runner_end_again asks the verb end-again with the pipeline and why. + {"end-again", "runner_end_again", "seat:mesh-pipeline-runner.end-again", "", map[string]any{"pipeline": "main.20", "why": "left running"}, + seat.EndAgainInput{Pipeline: "main.20", Why: "left running"}}, + {"end-again no why", "runner_end_again", "", "names why", map[string]any{"pipeline": "main.20"}, nil}, {"ask-again no why", "runner_ask_again", "", "names why", map[string]any{"pipeline": "p"}, nil}, } { t.Run(c.name, func(t *testing.T) { diff --git a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline/verbs.go b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline/verbs.go index 3d452e2b..20a754bc 100644 --- a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline/verbs.go +++ b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline/verbs.go @@ -38,7 +38,7 @@ func answerVerbs(conn *process.Conn, seats *seatlist.Part, v pipeline.Verbs) (fu return conn.AnswerSeat(seat.Seat, seatlist.Definition(seats.Reader, seat.Seat), writeHandlers(v)) } -// writeHandlers are the seat's write verbs the process answers: run, review, rerun, accept, cancel, start, and ask-again; and +// writeHandlers are the seat's write verbs the process answers: run, review, rerun, accept, cancel, end-again, start, and ask-again; and // the test runs' verbs test-runs and test-runs-drop (A-469g, A-470i). func writeHandlers(v pipeline.Verbs) map[string]process.SeatHandler { return map[string]process.SeatHandler{ @@ -47,6 +47,7 @@ func writeHandlers(v pipeline.Verbs) map[string]process.SeatHandler { seat.VerbRerun: verbOf(func(c string, in seat.RerunInput) (any, error) { return v.Rerun(c, in) }), seat.VerbAccept: verbOf(func(c string, in seat.AcceptInput) (any, error) { return v.Accept(c, in) }), seat.VerbCancel: verbOf(func(c string, in seat.CancelInput) (any, error) { return v.Cancel(c, in) }), + seat.VerbEndAgain: verbOf(func(c string, in seat.EndAgainInput) (any, error) { return v.EndAgain(c, in) }), seat.VerbPlace: verbOf(func(c string, in seat.PlaceInput) (any, error) { return v.Place(c, in) }), seat.VerbStart: verbOf(func(c string, in seat.StartInput) (any, error) { return v.Start(c, in) }), seat.VerbAskAgain: verbOf(func(c string, in seat.AskAgainInput) (any, error) { return v.AskAgain(c, in) }), diff --git a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline/verbs_test.go b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline/verbs_test.go index e9e203fe..d5745ddc 100644 --- a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline/verbs_test.go +++ b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline/verbs_test.go @@ -23,7 +23,7 @@ func TestEveryWriteVerbIsServed(t *testing.T) { got = append(got, v) } slices.Sort(got) - want := []string{seat.VerbAccept, seat.VerbAskAgain, seat.VerbCancel, seat.VerbPlace, seat.VerbRerun, seat.VerbReview, seat.VerbStart, seat.VerbRun, seat.VerbTestRuns, seat.VerbTestRunsDrop} + want := []string{seat.VerbAccept, seat.VerbAskAgain, seat.VerbCancel, seat.VerbEndAgain, seat.VerbPlace, seat.VerbRerun, seat.VerbReview, seat.VerbStart, seat.VerbRun, seat.VerbTestRuns, seat.VerbTestRunsDrop} slices.Sort(want) if !slices.Equal(got, want) { t.Errorf("the process answers %v, want %v", got, want) diff --git a/modules/mesh-delivery-pipeline/internal/pipeline/verbs.go b/modules/mesh-delivery-pipeline/internal/pipeline/verbs.go index d7aed473..5264f76e 100644 --- a/modules/mesh-delivery-pipeline/internal/pipeline/verbs.go +++ b/modules/mesh-delivery-pipeline/internal/pipeline/verbs.go @@ -244,6 +244,24 @@ func (v Verbs) Cancel(caller string, in seat.CancelInput) (seat.CancelAnswer, er } } +// EndAgain judges a running pipeline's end once more by hand, recorded in the hand-act log first (design 47 H §746, +// H-A-163, H-A-164): it ends as at a step's end, failed as soon as it can no longer pass, and says it, taking its turn in +// the queue; one that still cannot end is answered running. A pipeline not running is refused. +func (v Verbs) EndAgain(_ string, in seat.EndAgainInput) (seat.EndAgainAnswer, error) { + p, _, err := v.change(in.Pipeline, seat.EventStepEnded, func() error { + return v.record(seat.VerbEndAgain, "judged the end of the pipeline "+in.Pipeline+" again", in.Why) + }, func(p *seat.Pipeline, _ time.Time) (int, error) { + if p.Outcome != seat.PipelineOutcomeRunning { + return -1, fmt.Errorf("the pipeline %s is %s, not running", in.Pipeline, p.Outcome) + } + return -1, nil + }) + if err != nil { + return seat.EndAgainAnswer{}, err + } + return seat.EndAgainAnswer{Pipeline: p}, nil +} + // 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 diff --git a/modules/mesh-delivery-pipeline/internal/pipeline/verbs_test.go b/modules/mesh-delivery-pipeline/internal/pipeline/verbs_test.go index 93db1039..ed3867e0 100644 --- a/modules/mesh-delivery-pipeline/internal/pipeline/verbs_test.go +++ b/modules/mesh-delivery-pipeline/internal/pipeline/verbs_test.go @@ -156,6 +156,28 @@ func TestAcceptRerunAndCancelWriteByCompareAndSetAndRecordTheirHandAct(t *testin t.Errorf("%d hand acts recorded, want accept, rerun, cancel (3): %v", n, *acts) } + // H-A-163, H-A-164: end-again judges a running pipeline's end once more, a hand act; a pipeline the judgement before + // left running (a mover waiting on its registration, a placed one failed, nothing open) ends failed naming that mover. + if _, err := v.EndAgain("operator", seat.EndAgainInput{Pipeline: pkey, Why: "again"}); err == nil || len(*acts) != 3 { + t.Errorf("end-again of a cancelled pipeline = %v, %d hand acts, want refused and none recorded", err, len(*acts)) + } + store["main.20"] = struct { + p seat.Pipeline + rev uint64 + }{seat.Pipeline{Pipeline: "main.20", Branch: "main", Source: 20, Outcome: seat.PipelineOutcomeRunning, + Movers: []seat.Mover{{Module: "app"}, {Module: "contracts"}}, Steps: []seat.StepResult{ + {Step: seat.StepResultStepBuild, Module: "app", Status: seat.StepResultStatusRequired, Outcome: seat.StepResultOutcomeFailed}}}, 1} + if _, err := v.EndAgain("operator", seat.EndAgainInput{Pipeline: "main.20"}); err == nil { + t.Error("an end-again with no why was taken") + } + e, err := v.EndAgain("operator", seat.EndAgainInput{Pipeline: "main.20", Why: "left running by the judgement before H-A-163"}) + if err != nil || e.Pipeline.Outcome != seat.PipelineOutcomeFailed || e.Pipeline.EndCount != 1 || !strings.Contains(e.Pipeline.Why, "contracts has no registration") { + t.Fatalf("end-again = %+v, %v, want main.20 ended failed naming contracts", e.Pipeline, err) + } + if last := (*said)[len(*said)-1]; !strings.HasPrefix(last, "pipeline-ended.") || len(*acts) != 4 || !strings.Contains((*acts)[3], "mesh-pipeline-runner.end-again") { + t.Errorf("end-again said %q and recorded %v, want pipeline-ended and its hand act", last, *acts) + } + // H-A-101 (1): on a pipeline of two movers a verb names the mover's module; one naming none, or a module the pipeline // does not move, is refused, and the module named picks that mover's step. two, store2, _, _, _, _ := verbsFixture() diff --git a/modules/mesh-delivery-pipeline/manifest_test.go b/modules/mesh-delivery-pipeline/manifest_test.go index ef484842..e500b0a8 100644 --- a/modules/mesh-delivery-pipeline/manifest_test.go +++ b/modules/mesh-delivery-pipeline/manifest_test.go @@ -114,7 +114,7 @@ func TestManifest(t *testing.T) { {"uses operator-channel", equalSets(m.Uses, []string{"operator-channel"})}, // RN25 (§539): the runner's tools carry the prefix runner_. {"first-view tools", equalSets(m.Tools, []string{"runner_first_views", "runner_first_view_again", "runner_health", "runner_unlogged", "runner_unlogged_append", - "runner_start", "runner_run", "runner_accept", "runner_ask_again", "runner_place", "runner_waiting", + "runner_start", "runner_run", "runner_accept", "runner_ask_again", "runner_place", "runner_end_again", "runner_waiting", "runner_test_runs", "runner_test_runs_drop"})}, // A-305 (ADR 0227 rule 8, ADR 0240 rule 2): the process is judged by its unit, as every process of mesh-delivery, // never by a tool of its own; runner_health stays a tool. diff --git a/modules/mesh-delivery-pipeline/module.json b/modules/mesh-delivery-pipeline/module.json index 7087669a..671a0b97 100644 --- a/modules/mesh-delivery-pipeline/module.json +++ b/modules/mesh-delivery-pipeline/module.json @@ -18,6 +18,7 @@ "rerun", "accept", "cancel", + "end-again", "place", "ask-again", "test-runs", @@ -36,6 +37,7 @@ "runner_accept", "runner_ask_again", "runner_place", + "runner_end_again", "runner_waiting", "runner_test_runs", "runner_test_runs_drop"