flow

func Parse ¶ added in v0.5.0

func Parse(data []byte) (Card, error)

Parse unmarshals data into a Card, then calls Validate. A JSON decode error, syntax or type mismatch, wraps the decode error with context. An invariant failure returns the Validate error unchanged. Parse ignores an unknown JSON field, matching envelope.Decode's forward-compatibility rule.

func Decode ¶

func Decode(data []byte) (Checkpoint, error)

Decode parses JSON and validates the result. Checkpoint binds no guard or action, so no registry is needed.

func New ¶

func New(steps []Step, panels []Panel) (*Definition, error)

New builds a Definition and validates the step graph. It rejects an empty ID, a duplicate ID, a missing dependency, a panel that names an unknown step, a panel that names one step twice, a panel whose members disagree on To, and a step ID named in two panels. Kahn's algorithm rejects a cycle. After the graph is proven acyclic, New also rejects a panel where one member's Needs closure reaches a fellow member of the same panel. It rejects a chained step in a panel of two or more members. It rejects a Sub nesting depth above eight. It rejects a step that combines Sub and Route, a branch step with no dependent, a panel that names a branch step, and a panel that names a direct dependent of a branch step. It rejects an AdmissionOnFailed step with no needs, and an AdmissionOnFailed step named in a panel. It rejects an invalid Retry policy, a Retry policy combined with Sub, and a Retry policy on a panel member. It rejects an invalid Loop policy, a Loop policy combined with a nil Sub, and a Loop policy on a panel member. It rejects a step that sets both Payload and PayloadFrom, and a PayloadFrom on a member of a panel of two or more members. It deep-copies the input slices so later caller mutation cannot change the built graph.

func FailureFrom ¶

func FailureFrom(ctx context.Context) (Failure, bool)

FailureFrom reads the failure context Run injects into a fallback step's Fire. The boolean is false outside a fallback firing.

func LoopStateFrom ¶

func LoopStateFrom(ctx context.Context) (LoopState, bool)

LoopStateFrom reads the LoopState runLoopedChild injects before each Guard call of a loop step. The boolean is false outside a loop step's Guard evaluation, matching FailureFrom's shape.

func NewMonitor ¶ added in v0.5.0

func NewMonitor(timeout time.Duration) (*Monitor, error)

NewMonitor creates a Monitor with a fixed timeout. A non-positive timeout wraps ErrInvalidOptions.

func Resume ¶

func Resume(
	ctx context.Context, d *Definition, m *machine.Definition,
	checkpoint Checkpoint, confirm Confirm, bus *events.Bus,
	onCheckpoint func(Checkpoint),
) (Report, error)

Resume restarts a graph walk from a stored checkpoint. It seeds outcomes from checkpoint.Done (every listed ID set to OutcomeSucceeded), checkpoint.Skipped (every listed ID set to OutcomeSkipped), and checkpoint.Failed (every listed ID set to OutcomeFailed), cur from checkpoint.Status, and rec from checkpoint.Record, then continues the same graph walk Run uses. A route exclusion or an admission skip captured before the pause stays skipped after Resume; a step already resolved OutcomeFailed before the pause, caught or not, is never re-run after Resume; nextReadyGroup and admissionVerdict never re-evaluate a step already seeded in outcomes. Resume runs five entry checks in order, before any seeding happens: a nil d, a nil m, a nil confirm, a checkpoint that fails Validate, and a checkpoint.Done, checkpoint.Skipped, or checkpoint.Failed entry naming a step ID absent from d. The first failing check returns an error immediately; no step runs.

Resume performs no topology check across Done: it never confirms that a step named in Done has every one of its own Needs also named in Done. A topologically-inconsistent checkpoint is not rejected at entry; nextReadyGroup treats a missing prerequisite as unresolved and selects it to run again, and the resulting pickTransition or machine.Fire call fails, because checkpoint.Status no longer names a status the seeded walk can reach that step from. Resume returns that failure as an ordinary error.

Resume starts pending empty; it does not restore a still-pending fallback's bookkeeping from before the pause. See Checkpoint.

func Run ¶

func Run(
	ctx context.Context, d *Definition, m *machine.Definition,
	in machine.InOut, confirm Confirm, bus *events.Bus,
	onCheckpoint func(Checkpoint),
) (Report, error)

Run walks the step graph in topological order. A step named in no panel runs alone, in declaration order, as it did before panels existed; Run calls confirm for that step. See Confirm. A step named in a panel of one member runs alone the same way, and Run calls confirm for it too. A step named in a panel of two or more members runs as part of that panel's wave, once every member is ready; the wave fires every member's transition concurrently through the one shared row every member's homogeneous To selects. Run does not call confirm for a wave of two or more members. A step with a non-nil Sub runs its child workflow to completion, then uses the child final status as the parent step's target status; the child runs with a nil bus. Run keeps the current status and one record through the walk. Run rejects a nil d, a nil m, and a nil confirm at entry, checking d first, then m, then confirm, so a nil m never panics inside a d-nil or m-nil check.

onCheckpoint, when non-nil, fires immediately after each step or wave resolves OutcomeSucceeded, with a fresh Checkpoint. A nil onCheckpoint skips the call. See Checkpoint and Resume.

Before each step or wave starts, Run checks ctx for cancellation. A canceled ctx stops the walk before the next step starts and returns the pinned pause error, wrapping ctx.Err(); the last Checkpoint onCheckpoint delivered is the resume point. A step already running keeps running to its own completion, unless cancellation is observed inside a retry loop or a looped child workflow; in those cases the current step aborts and returns the context error.

Run returns a Report holding the final status, the final record, and every resolved step's Outcome. On every abort, Run returns the Report built so far, alongside the error. A step whose Fire fails or whose Confirm is rejected is marked OutcomeFailed before the return. A wave's shared, pre-spawn transition failure marks no member of that wave; a per-member Fire failure inside a wave marks every member OutcomeFailed, whether or not a dependent's AdmissionOnFailed rule catches the failure. A step admitted through a failed need (AdmissionOnFailed) is a fallback; Run injects a Failure into its transition's context, and FailureFrom reads it back. A caught Fire or Route failure continues down the fallback path; a Confirm rejection or a missing transition row stays fatal. Checkpoint's Failed field preserves an already-caught failure's outcome across a pause; see Checkpoint for what does not survive.

A panel member's Input and Output must be an immutable value, or a value the caller already cloned per step. Run's copy of each member's InOut is shallow: a map, a slice, or a pointer an Input or Output field holds is not copied. Two members that alias the same data still race if either mutates it in place.