Files
archie/internal/taskstate/transitions.go
T

105 lines
3.6 KiB
Go

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
}