feat(taskstate): transition tables for executions and steps
This commit is contained in:
1 parent
cca9e20598
commit
ef8a45d4b7
2 files changed
+359
No files matched your search
@@ -0,0 +1,104 @@
|
||||
package taskstate
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"fmt"
|
||||
"slices"
|
||||
)
|
||||
|
||||
// StepStatus is the lifecycle of a StepExecution -- one stage run, or one agent
|
||||
// call a stage makes, inside a WorkflowExecution
|
||||
// (docs/prds/execution-tree-state-machine.md). It is part of the on-disk
|
||||
// format, like the execution statuses above.
|
||||
//
|
||||
// It is a distinct type from those statuses even though the two vocabularies
|
||||
// share the word "running": an execution status says what the task is doing,
|
||||
// a step status says what one stage is doing, and the two move through
|
||||
// different tables. One shared string type would let either status be passed
|
||||
// where the other belongs, which is the mistake the separate tables exist to
|
||||
// catch.
|
||||
type StepStatus string
|
||||
|
||||
const (
|
||||
StepPending StepStatus = "pending"
|
||||
StepRunning StepStatus = "running"
|
||||
StepSucceeded StepStatus = "succeeded"
|
||||
StepFailed StepStatus = "failed"
|
||||
StepCancelled StepStatus = "cancelled"
|
||||
StepInterrupted StepStatus = "interrupted"
|
||||
)
|
||||
|
||||
// executionTransitions is the WorkflowExecution table: the complete set of
|
||||
// legal status moves, held as data so no writer carries its own conditional
|
||||
// copy of the rules.
|
||||
//
|
||||
// Terminal statuses appear as empty rows rather than being absent, so the
|
||||
// table is total over the vocabulary: a status that is missing here is
|
||||
// unroutable, and the difference between "goes nowhere" and "nobody wrote a
|
||||
// row" stays visible.
|
||||
var executionTransitions = map[string][]string{
|
||||
Queued: {Running, Declined},
|
||||
Running: {Queued, WaitingHuman, PROpen, Completed, Parked, Declined},
|
||||
WaitingHuman: {Queued, Declined},
|
||||
Parked: {Queued, Dead, Declined},
|
||||
PROpen: {Merged, Rejected, Queued, Declined},
|
||||
|
||||
Merged: nil,
|
||||
Rejected: nil,
|
||||
Dead: nil,
|
||||
Declined: nil,
|
||||
Completed: nil,
|
||||
}
|
||||
|
||||
// stepTransitions is the StepExecution table, the same shape over the step
|
||||
// vocabulary.
|
||||
var stepTransitions = map[StepStatus][]StepStatus{
|
||||
StepPending: {StepRunning, StepCancelled},
|
||||
StepRunning: {StepSucceeded, StepFailed, StepCancelled, StepInterrupted},
|
||||
|
||||
StepSucceeded: nil,
|
||||
StepFailed: nil,
|
||||
StepCancelled: nil,
|
||||
StepInterrupted: nil,
|
||||
}
|
||||
|
||||
// CanTransition reports whether a WorkflowExecution may move from one status to
|
||||
// another. The pair must appear in executionTransitions: an unknown status on
|
||||
// either side is illegal, and a terminal status has no way out.
|
||||
func CanTransition(from, to string) bool {
|
||||
return slices.Contains(executionTransitions[from], to)
|
||||
}
|
||||
|
||||
// CanStepTransition reports whether a StepExecution may move from one status to
|
||||
// another, under the same rules.
|
||||
func CanStepTransition(from, to StepStatus) bool {
|
||||
return slices.Contains(stepTransitions[from], to)
|
||||
}
|
||||
|
||||
// StepTerminal reports whether a step status is an end state. A finished step
|
||||
// only moves again as a fresh step in a new attempt.
|
||||
func StepTerminal(status StepStatus) bool {
|
||||
switch status {
|
||||
case StepSucceeded, StepFailed, StepCancelled, StepInterrupted:
|
||||
return true
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
// CheckStepStart reports whether a StepExecution may enter StepRunning under
|
||||
// the execution it belongs to.
|
||||
//
|
||||
// A step only runs while its execution is running, and never under a parent
|
||||
// that has already finished: work a terminal parent had going was cancelled or
|
||||
// interrupted when it finished, so a step starting afterwards would be recorded
|
||||
// against a decision that has already been taken.
|
||||
func CheckStepStart(executionStatus string, parentTerminal bool) error {
|
||||
if executionStatus != Running {
|
||||
return fmt.Errorf("step cannot start while its execution is %s", executionStatus)
|
||||
}
|
||||
if parentTerminal {
|
||||
return errors.New("step cannot start under a terminal parent")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
@@ -0,0 +1,255 @@
|
||||
package taskstate
|
||||
|
||||
import (
|
||||
"slices"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// The legal pairs are written out here rather than read from the map under
|
||||
// test. A table-driven test that derived its expectation from the table would
|
||||
// hold for any table, including an empty one.
|
||||
var legalExecutionTransitions = []struct{ from, to string }{
|
||||
{Queued, Running},
|
||||
{Queued, Declined},
|
||||
{Running, Queued},
|
||||
{Running, WaitingHuman},
|
||||
{Running, PROpen},
|
||||
{Running, Completed},
|
||||
{Running, Parked},
|
||||
{Running, Declined},
|
||||
{WaitingHuman, Queued},
|
||||
{WaitingHuman, Declined},
|
||||
{Parked, Queued},
|
||||
{Parked, Dead},
|
||||
{Parked, Declined},
|
||||
{PROpen, Merged},
|
||||
{PROpen, Rejected},
|
||||
{PROpen, Queued},
|
||||
{PROpen, Declined},
|
||||
}
|
||||
|
||||
var legalStepTransitions = []struct{ from, to StepStatus }{
|
||||
{StepPending, StepRunning},
|
||||
{StepPending, StepCancelled},
|
||||
{StepRunning, StepSucceeded},
|
||||
{StepRunning, StepFailed},
|
||||
{StepRunning, StepCancelled},
|
||||
{StepRunning, StepInterrupted},
|
||||
}
|
||||
|
||||
func statusIDs() []string {
|
||||
ids := make([]string, 0, len(Statuses()))
|
||||
for _, meta := range Statuses() {
|
||||
ids = append(ids, meta.ID)
|
||||
}
|
||||
return ids
|
||||
}
|
||||
|
||||
func execPair(from, to string) string { return from + " -> " + to }
|
||||
|
||||
// The whole cross product, not a sample: every pair the vocabulary can
|
||||
// express is checked against the legal set, so an edge nobody meant to add
|
||||
// fails here rather than at the store.
|
||||
func TestExecutionTransitionTableIsExactlyThePRDTable(t *testing.T) {
|
||||
known := statusIDs()
|
||||
legal := map[string]bool{}
|
||||
for _, p := range legalExecutionTransitions {
|
||||
if !slices.Contains(known, p.from) || !slices.Contains(known, p.to) {
|
||||
t.Fatalf("legal pair %s names a status the catalog does not present", execPair(p.from, p.to))
|
||||
}
|
||||
if legal[execPair(p.from, p.to)] {
|
||||
t.Fatalf("duplicate legal pair %s", execPair(p.from, p.to))
|
||||
}
|
||||
legal[execPair(p.from, p.to)] = true
|
||||
}
|
||||
|
||||
for _, from := range known {
|
||||
for _, to := range known {
|
||||
want := legal[execPair(from, to)]
|
||||
if got := CanTransition(from, to); got != want {
|
||||
t.Errorf("CanTransition(%s) = %v, want %v", execPair(from, to), got, want)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// The PRD names one write the store accepts today and the table must refuse:
|
||||
// a queued task cannot be born merged. It is the pair a table that only
|
||||
// checked "is this a known status" would still let through.
|
||||
func TestQueuedCannotReachMerged(t *testing.T) {
|
||||
if CanTransition(Queued, Merged) {
|
||||
t.Error("CanTransition(queued, merged) = true; the transition tables section names this pair as illegal")
|
||||
}
|
||||
}
|
||||
|
||||
// An unknown status must be illegal in both positions. A status written by a
|
||||
// newer version, or a typo, must not be able to start or end a transition.
|
||||
func TestUnknownStatusIsNeverATransition(t *testing.T) {
|
||||
const unknown = "quantum_superposition"
|
||||
for _, status := range statusIDs() {
|
||||
if CanTransition(unknown, status) {
|
||||
t.Errorf("CanTransition(%s -> %s) = true", unknown, status)
|
||||
}
|
||||
if CanTransition(status, unknown) {
|
||||
t.Errorf("CanTransition(%s -> %s) = true", status, unknown)
|
||||
}
|
||||
}
|
||||
if CanTransition(unknown, unknown) {
|
||||
t.Errorf("CanTransition(%s -> %s) = true", unknown, unknown)
|
||||
}
|
||||
if CanStepTransition(StepStatus(unknown), StepPending) {
|
||||
t.Errorf("CanStepTransition(%s -> %s) = true", unknown, StepPending)
|
||||
}
|
||||
if CanStepTransition(StepRunning, StepStatus(unknown)) {
|
||||
t.Errorf("CanStepTransition(%s -> %s) = true", StepRunning, unknown)
|
||||
}
|
||||
}
|
||||
|
||||
// Rows must cover the vocabulary, and only the vocabulary. A status added to
|
||||
// the presentation catalog without a row would be unroutable -- no writer
|
||||
// could move a task into or out of it -- and the failure would surface as a
|
||||
// task stuck in a state, long after the edit.
|
||||
func TestTransitionRowsCoverTheStatusVocabulary(t *testing.T) {
|
||||
known := map[string]bool{}
|
||||
for _, id := range statusIDs() {
|
||||
known[id] = true
|
||||
if _, ok := executionTransitions[id]; !ok {
|
||||
t.Errorf("status %q has no row in executionTransitions", id)
|
||||
}
|
||||
}
|
||||
for from := range executionTransitions {
|
||||
if !known[from] {
|
||||
t.Errorf("executionTransitions has a row for %q, which the catalog does not present", from)
|
||||
}
|
||||
for _, to := range executionTransitions[from] {
|
||||
if !known[to] {
|
||||
t.Errorf("executionTransitions row %q names %q, which the catalog does not present", from, to)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// A terminal status has no way out and a live one must have at least one way
|
||||
// forward: a live status with no edges strands every task that reaches it.
|
||||
func TestTerminalAndRoutableRowsAgree(t *testing.T) {
|
||||
for _, id := range statusIDs() {
|
||||
if got, want := len(executionTransitions[id]) == 0, Terminal(id); got != want {
|
||||
t.Errorf("status %q: row is empty = %v, Terminal = %v", id, got, want)
|
||||
}
|
||||
}
|
||||
for _, status := range stepVocabulary() {
|
||||
if got, want := len(stepTransitions[status]) == 0, StepTerminal(status); got != want {
|
||||
t.Errorf("step %q: row is empty = %v, StepTerminal = %v", status, got, want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func stepVocabulary() []StepStatus {
|
||||
return []StepStatus{StepPending, StepRunning, StepSucceeded, StepFailed, StepCancelled, StepInterrupted}
|
||||
}
|
||||
|
||||
func TestStepTransitionTableIsExactlyThePRDTable(t *testing.T) {
|
||||
known := stepVocabulary()
|
||||
legal := map[StepStatus]bool{}
|
||||
for _, p := range legalStepTransitions {
|
||||
if !slices.Contains(known, p.from) || !slices.Contains(known, p.to) {
|
||||
t.Fatalf("legal pair %s -> %s names a step status not in the vocabulary", p.from, p.to)
|
||||
}
|
||||
legal[p.from+"->"+p.to] = true
|
||||
}
|
||||
|
||||
for _, from := range known {
|
||||
for _, to := range known {
|
||||
want := legal[from+"->"+to]
|
||||
if got := CanStepTransition(from, to); got != want {
|
||||
t.Errorf("CanStepTransition(%s -> %s) = %v, want %v", from, to, got, want)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestStepTransitionRowsCoverTheStepVocabulary(t *testing.T) {
|
||||
known := map[StepStatus]bool{}
|
||||
for _, status := range stepVocabulary() {
|
||||
known[status] = true
|
||||
if _, ok := stepTransitions[status]; !ok {
|
||||
t.Errorf("step status %q has no row in stepTransitions", status)
|
||||
}
|
||||
}
|
||||
for from := range stepTransitions {
|
||||
if !known[from] {
|
||||
t.Errorf("stepTransitions has a row for unknown step status %q", from)
|
||||
}
|
||||
for _, to := range stepTransitions[from] {
|
||||
if !known[to] {
|
||||
t.Errorf("stepTransitions row %q names unknown step status %q", from, to)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Two ways for a step to stop early, and they must not be confused:
|
||||
// cancelled is someone asking, interrupted is the process dying.
|
||||
func TestStepTerminal(t *testing.T) {
|
||||
terminals := []StepStatus{StepSucceeded, StepFailed, StepCancelled, StepInterrupted}
|
||||
for _, status := range stepVocabulary() {
|
||||
want := slices.Contains(terminals, status)
|
||||
if got := StepTerminal(status); got != want {
|
||||
t.Errorf("StepTerminal(%s) = %v, want %v", status, got, want)
|
||||
}
|
||||
}
|
||||
if StepTerminal(StepStatus("half_written")) {
|
||||
t.Error("StepTerminal(unknown) = true")
|
||||
}
|
||||
}
|
||||
|
||||
// The step vocabulary is separate and stays out of the execution catalog: a
|
||||
// step status listed in Statuses() would show the dashboard a task status no
|
||||
// task can have.
|
||||
func TestStepVocabularyStaysOutOfTheExecutionCatalog(t *testing.T) {
|
||||
ids := statusIDs()
|
||||
for _, status := range stepVocabulary() {
|
||||
if string(status) == Running {
|
||||
// The two vocabularies deliberately share this word.
|
||||
continue
|
||||
}
|
||||
if slices.Contains(ids, string(status)) {
|
||||
t.Errorf("step status %q is presented as an execution status", status)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// A step may only enter running while its execution is running, and never
|
||||
// under a parent that is already terminal: a finished parent's children were
|
||||
// cancelled or interrupted when it finished.
|
||||
func TestCheckStepStart(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
execution string
|
||||
parentTerminal bool
|
||||
wantErr bool
|
||||
}{
|
||||
{name: "running execution, live parent", execution: Running},
|
||||
{name: "running execution, terminal parent", execution: Running, parentTerminal: true, wantErr: true},
|
||||
{name: "queued execution", execution: Queued, wantErr: true},
|
||||
{name: "execution waiting on a human", execution: WaitingHuman, wantErr: true},
|
||||
{name: "execution parked", execution: Parked, wantErr: true},
|
||||
{name: "execution with a pull request open", execution: PROpen, wantErr: true},
|
||||
{name: "terminal execution", execution: Merged, wantErr: true},
|
||||
{name: "unknown execution", execution: "quantum_superposition", wantErr: true},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
err := CheckStepStart(tt.execution, tt.parentTerminal)
|
||||
if got := err != nil; got != tt.wantErr {
|
||||
t.Errorf("CheckStepStart(%q, %v) error = %v, want error = %v", tt.execution, tt.parentTerminal, err, tt.wantErr)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
for _, id := range statusIDs() {
|
||||
if err := CheckStepStart(id, false); (err != nil) != (id != Running) {
|
||||
t.Errorf("CheckStepStart(%q, false) = %v, want error exactly when %q is not running", id, err, id)
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user