docs(runs): plain the comments on run endings (#2042)
This commit is contained in:
5 files changed
+20
-18
No files matched your search
@@ -1,8 +1,9 @@
|
|||||||
-- +goose Up
|
-- +goose Up
|
||||||
-- A run can end in four ways beyond success and failure: a step parks it for an
|
-- Besides succeeding or failing, a run can now end parked, waiting for approval
|
||||||
-- operator to retry, a workflow.finish step ends it waiting for approval or
|
-- or declined. A failed step or a workflow.finish step parks a run for an
|
||||||
-- declined, and detail carries what the ending says. A parked or waiting run is
|
-- operator to retry from a step; a workflow.finish step can also leave it
|
||||||
-- not terminal: parked runs retry from a step.
|
-- waiting for approval or declined. detail explains the ending. Parked and
|
||||||
|
-- waiting runs are not terminal.
|
||||||
ALTER TABLE runs.runs DROP CONSTRAINT runs_runs_state_check;
|
ALTER TABLE runs.runs DROP CONSTRAINT runs_runs_state_check;
|
||||||
ALTER TABLE runs.runs ADD CONSTRAINT runs_runs_state_check
|
ALTER TABLE runs.runs ADD CONSTRAINT runs_runs_state_check
|
||||||
CHECK (state IN ('queued', 'running', 'waiting', 'succeeded', 'failed', 'cancelled',
|
CHECK (state IN ('queued', 'running', 'waiting', 'succeeded', 'failed', 'cancelled',
|
||||||
|
|||||||
@@ -47,8 +47,8 @@ type Context struct {
|
|||||||
nextMarker int
|
nextMarker int
|
||||||
// entered holds the top-level steps an earlier attempt reached.
|
// entered holds the top-level steps an earlier attempt reached.
|
||||||
entered map[string]bool
|
entered map[string]bool
|
||||||
// ending is how the workflow ended when it ended other than by running out
|
// ending is set when the run ends before its last step. A run that
|
||||||
// of steps, which is a success.
|
// completes every step has no ending and succeeds.
|
||||||
ending *Ending
|
ending *Ending
|
||||||
// overlay is what a dry run carries instead of a stored version.
|
// overlay is what a dry run carries instead of a stored version.
|
||||||
overlay *dryOverlay
|
overlay *dryOverlay
|
||||||
@@ -106,7 +106,7 @@ func (rc *Context) Begin(ctx context.Context, key string) (bool, error) {
|
|||||||
|
|
||||||
// Enter records that the top-level step name begins at the run's next position,
|
// Enter records that the top-level step name begins at the run's next position,
|
||||||
// unless an earlier attempt already did. Retrying a parked run from the step
|
// unless an earlier attempt already did. Retrying a parked run from the step
|
||||||
// forgets everything recorded from that position on.
|
// discards everything recorded from that position onwards.
|
||||||
func (rc *Context) Enter(ctx context.Context, name string) error {
|
func (rc *Context) Enter(ctx context.Context, name string) error {
|
||||||
if rc.entered[name] {
|
if rc.entered[name] {
|
||||||
return nil
|
return nil
|
||||||
@@ -120,17 +120,18 @@ func (rc *Context) Enter(ctx context.Context, name string) error {
|
|||||||
return nil
|
return nil
|
||||||
}
|
}
|
||||||
|
|
||||||
// End records how the workflow ends, ahead of its steps running out.
|
// End records that the run ends before its last step, with this state and
|
||||||
|
// detail.
|
||||||
func (rc *Context) End(state, detail string) {
|
func (rc *Context) End(state, detail string) {
|
||||||
rc.ending = &Ending{State: state, Detail: detail}
|
rc.ending = &Ending{State: state, Detail: detail}
|
||||||
}
|
}
|
||||||
|
|
||||||
// Ending is how a run that stopped before its steps ran out ended.
|
// Ending describes how a run ended before its last step.
|
||||||
type Ending struct {
|
type Ending struct {
|
||||||
// State is the run state the ending sets.
|
// State is the run state that the ending sets.
|
||||||
State string
|
State string
|
||||||
// Detail is what the ending says: a finish step's detail or why a step
|
// Detail is the finish step's detail, or the reason a step parked the
|
||||||
// parked the run.
|
// run.
|
||||||
Detail string
|
Detail string
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -209,8 +209,8 @@ func (s *Store) Suspend(ctx context.Context, id, token uuid.UUID, wakeAt *time.T
|
|||||||
return nil
|
return nil
|
||||||
}
|
}
|
||||||
|
|
||||||
// Ended is how a run ended. Error is a failure's text and Detail what an
|
// Ended describes how a run ended. Error is the failure text, and Detail is
|
||||||
// ending says, such as a workflow.finish step's detail.
|
// the ending's explanation, such as a workflow.finish step's detail.
|
||||||
type Ended struct {
|
type Ended struct {
|
||||||
State string
|
State string
|
||||||
Result jsontext.Value
|
Result jsontext.Value
|
||||||
|
|||||||
@@ -132,8 +132,8 @@ type progress struct {
|
|||||||
agent *AgentResult
|
agent *AgentResult
|
||||||
memory bool
|
memory bool
|
||||||
remembered bool
|
remembered bool
|
||||||
// last is what the most recent step that ran reported, which a run that
|
// last is the summary of the most recent step. A run that completes every
|
||||||
// reaches the end of its steps gives as its detail.
|
// step uses it as its detail.
|
||||||
last string
|
last string
|
||||||
outcomes []approvalOutcome
|
outcomes []approvalOutcome
|
||||||
// settled is the actions already put to people, by digest, so a later
|
// settled is the actions already put to people, by digest, so a later
|
||||||
@@ -450,7 +450,7 @@ func (p *progress) result() (jsontext.Value, error) {
|
|||||||
return out, nil
|
return out, nil
|
||||||
}
|
}
|
||||||
|
|
||||||
// encode is the run's findings so far, as the result a run records.
|
// encode returns the run's findings so far as the result that the run records.
|
||||||
func (p *progress) encode() (jsontext.Value, error) {
|
func (p *progress) encode() (jsontext.Value, error) {
|
||||||
var v any = p.outcomes
|
var v any = p.outcomes
|
||||||
if p.agent != nil {
|
if p.agent != nil {
|
||||||
|
|||||||
@@ -46,7 +46,7 @@ type RunView struct {
|
|||||||
State string `json:"state"`
|
State string `json:"state"`
|
||||||
Attempts int `json:"attempts"`
|
Attempts int `json:"attempts"`
|
||||||
Error string `json:"error,omitzero"`
|
Error string `json:"error,omitzero"`
|
||||||
// Detail is what the run's ending says: a finish step's detail, or why a
|
// Detail explains how the run ended: a finish step's detail, or why a
|
||||||
// step parked the run.
|
// step parked the run.
|
||||||
Detail string `json:"detail,omitzero"`
|
Detail string `json:"detail,omitzero"`
|
||||||
CreatedAt time.Time `json:"created_at"`
|
CreatedAt time.Time `json:"created_at"`
|
||||||
|
|||||||
Reference in new issue
Block a user