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
|
||||
-- A run can end in four ways beyond success and failure: a step parks it for an
|
||||
-- operator to retry, a workflow.finish step ends it waiting for approval or
|
||||
-- declined, and detail carries what the ending says. A parked or waiting run is
|
||||
-- not terminal: parked runs retry from a step.
|
||||
-- Besides succeeding or failing, a run can now end parked, waiting for approval
|
||||
-- or declined. A failed step or a workflow.finish step parks a run for an
|
||||
-- operator to retry from a step; a workflow.finish step can also leave it
|
||||
-- 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 ADD CONSTRAINT runs_runs_state_check
|
||||
CHECK (state IN ('queued', 'running', 'waiting', 'succeeded', 'failed', 'cancelled',
|
||||
|
||||
@@ -47,8 +47,8 @@ type Context struct {
|
||||
nextMarker int
|
||||
// entered holds the top-level steps an earlier attempt reached.
|
||||
entered map[string]bool
|
||||
// ending is how the workflow ended when it ended other than by running out
|
||||
// of steps, which is a success.
|
||||
// ending is set when the run ends before its last step. A run that
|
||||
// completes every step has no ending and succeeds.
|
||||
ending *Ending
|
||||
// overlay is what a dry run carries instead of a stored version.
|
||||
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,
|
||||
// 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 {
|
||||
if rc.entered[name] {
|
||||
return nil
|
||||
@@ -120,17 +120,18 @@ func (rc *Context) Enter(ctx context.Context, name string) error {
|
||||
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) {
|
||||
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 {
|
||||
// State is the run state the ending sets.
|
||||
// State is the run state that the ending sets.
|
||||
State string
|
||||
// Detail is what the ending says: a finish step's detail or why a step
|
||||
// parked the run.
|
||||
// Detail is the finish step's detail, or the reason a step parked the
|
||||
// run.
|
||||
Detail string
|
||||
}
|
||||
|
||||
|
||||
@@ -209,8 +209,8 @@ func (s *Store) Suspend(ctx context.Context, id, token uuid.UUID, wakeAt *time.T
|
||||
return nil
|
||||
}
|
||||
|
||||
// Ended is how a run ended. Error is a failure's text and Detail what an
|
||||
// ending says, such as a workflow.finish step's detail.
|
||||
// Ended describes how a run ended. Error is the failure text, and Detail is
|
||||
// the ending's explanation, such as a workflow.finish step's detail.
|
||||
type Ended struct {
|
||||
State string
|
||||
Result jsontext.Value
|
||||
|
||||
@@ -132,8 +132,8 @@ type progress struct {
|
||||
agent *AgentResult
|
||||
memory bool
|
||||
remembered bool
|
||||
// last is what the most recent step that ran reported, which a run that
|
||||
// reaches the end of its steps gives as its detail.
|
||||
// last is the summary of the most recent step. A run that completes every
|
||||
// step uses it as its detail.
|
||||
last string
|
||||
outcomes []approvalOutcome
|
||||
// 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
|
||||
}
|
||||
|
||||
// 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) {
|
||||
var v any = p.outcomes
|
||||
if p.agent != nil {
|
||||
|
||||
@@ -46,7 +46,7 @@ type RunView struct {
|
||||
State string `json:"state"`
|
||||
Attempts int `json:"attempts"`
|
||||
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.
|
||||
Detail string `json:"detail,omitzero"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
|
||||
Reference in new issue
Block a user