Documentation
¶
Overview ¶
Package directive defines typed directive constants for the workflow step and group execution system. Directives control the flow of execution: whether to continue, stop, retry, or skip.
There are two levels:
- Step directives: written by step Execute() into the step's ResultDirective
- Group directives: written by group Execute() into the group's ResultDirective
The flow executor reads group directives to decide workflow-level behavior. The group's sequential loop reads step directives to decide group-level behavior.
Index ¶
Constants ¶
const MetadataKey = "directive"
MetadataKey is the key used to store the directive in status metadata.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ApprovalCreateCheck ¶
type ApprovalCreateCheck interface {
Name() string
ShouldRun(step *app.WorkflowStep, flw *app.Workflow) bool
Run(ctx workflow.Context, step *app.WorkflowStep, flw *app.Workflow) (CheckResult, error)
}
ApprovalCreateCheck runs BEFORE the approval is presented to the user. Return StepUnknown to pass through; any other directive short-circuits.
type ApprovalResponseCheck ¶
type ApprovalResponseCheck interface {
Name() string
ShouldRun(step *app.WorkflowStep, flw *app.Workflow, resp *app.WorkflowStepApprovalResponse) bool
Run(ctx workflow.Context, step *app.WorkflowStep, flw *app.Workflow, resp *app.WorkflowStepApprovalResponse) (CheckResult, error)
}
ApprovalResponseCheck runs AFTER an approval response is received. Return StepUnknown to let the normal response handler run; any other directive overrides it.
type CheckContext ¶
type CheckContext struct {
NoopPlan bool
}
CheckContext carries state shared between checks in a single pipeline run.
type CheckReason ¶
type CheckReason struct {
// Check is the identifier of the check (e.g. "noop", "policy", "stale-plan").
Check string
// Summary is a human-readable one-liner shown in the dashboard.
Summary string
// Detail is a longer explanation shown in step details.
Detail string
// Labels are machine-readable key-value pairs for filtering/routing.
Labels map[string]string
}
CheckReason carries structured metadata about why a check produced its result.
func (CheckReason) Metadata ¶
func (r CheckReason) Metadata() map[string]any
Metadata returns the reason as a map suitable for CompositeStatus.Metadata.
type CheckResult ¶
type CheckResult struct {
Directive Step
Reason CheckReason
// Status overrides the step status written by applyCheckResult.
// When empty, defaults to StatusError for backward compatibility.
Status app.Status
}
CheckResult is the outcome of an approval check: a directive and a reason. StepUnknown (empty) means "no opinion, continue to next check." Any other directive short-circuits the pipeline.
type Group ¶
type Group string
Group is the typed directive written by group Execute() into the group's ResultDirective. The flow executor reads this after the group's queue signal completes.
const ( // GroupContinue means the group completed. The flow proceeds to the next group. GroupContinue Group = "continue" // GroupStop means the group stopped. The flow marks remaining groups as discarded. GroupStop Group = "stop" // GroupRetryGroup means the group should be cloned and retried. // The flow creates a new group with cloned steps and re-dispatches. GroupRetryGroup Group = "retry-group" // GroupSkipGroup means the group was skipped (e.g., noop plan). // The flow proceeds to the next group. GroupSkipGroup Group = "skip-group" // GroupAwaitApproval means the group is awaiting approval. GroupAwaitApproval Group = "await-approval" )
type Step ¶
type Step string
Step is the typed directive written by step Execute() into the step's ResultDirective. The group reads this after the step's queue signal completes.
const ( // StepContinue means the step succeeded. The group proceeds to the next step. StepContinue Step = "continue" // StepStop means the step failed terminally. The group stops and the workflow errors. StepStop Step = "stop" // StepRetry means the step should be cloned and retried individually. // The group creates a clone and picks it up on the next loop iteration. StepRetry Step = "retry" // StepRetryGroup means the entire group should be cloned and retried. // The group propagates this to the flow, which handles group-level cloning. StepRetryGroup Step = "retry-group" // StepSkipGroup means the remaining steps in the group should be skipped. // Used when a plan detects no changes (noop). StepSkipGroup Step = "skip-group" // StepAwaitApproval means the step is awaiting user approval. Execute() // blocks internally until the approval is resolved. StepAwaitApproval Step = "await-approval" // StepAwaitRetry means auto-retries are exhausted but manual retries remain. // Execute() blocks internally until the user retries or skips. StepAwaitRetry Step = "await-retry" )
const StepUnknown Step = ""
StepUnknown means the check has no opinion — pass through to the next check.
func (Step) IsTerminal ¶
IsTerminal returns true if the directive represents a completed step that the group should act on. Non-terminal directives (await-approval, await-retry) mean Execute() is still blocking — the group should not see these.
type StepResult ¶
type StepResult struct {
// Directive is the typed step directive.
Directive Step
// Reason is a human-readable description of why this directive was issued.
// Written to the step's status and propagated to remaining step metadata.
// Examples: "approval denied", "max retries exhausted", "noop plan".
Reason string
// SiblingStatus is the status to apply to remaining steps in the SAME group
// when the directive is StepStop or StepSkipGroup. Defaults to StatusDiscarded.
SiblingStatus app.Status
// FutureStatus is the status to apply to steps in FUTURE groups when the
// directive is StepStop. If empty, defaults to StatusNotAttempted.
FutureStatus app.Status
}
StepResult carries the directive along with metadata that controls how the group and flow set statuses on remaining steps. This allows the step to communicate context (e.g., "denied" vs "error") to the group/flow.
func NewStepResult ¶
func NewStepResult(d Step) StepResult
NewStepResult creates a StepResult with sensible defaults.
Source Files