order sagas

pkg/flow/flow.go

@@ -0,0 +1,67 @@
+// Package flow is a generic, JSON-configurable orchestration engine. A flow is a
+// sequence of named steps; each step runs a registered action, may be gated by a
+// registered predicate, can fire registered hooks (before/after/on-error), and
+// may declare a compensating action used to roll back on failure (the saga
+// pattern). Actions, predicates and hooks are registered by name — the same
+// "interface + interchangeable impls, wired in one place" seam the CMS uses for
+// its event listeners. The flow definition itself is plain JSON, so flows live
+// alongside the app's other JSON config (schemas, blueprints) and can be edited
+// without code changes.
+package flow
+
+import "encoding/json"
+
+// Definition is a whole flow, loadable from JSON.
+type Definition struct {
+	Name        string `json:"name"`
+	Description string `json:"description,omitempty"`
+	Steps       []Step `json:"steps"`
+}
+
+// Step is one unit of work in a flow.
+type Step struct {
+	// Name identifies the step in logs, hooks and results.
+	Name string `json:"name"`
+	// Action is the registered action to run.
+	Action string `json:"action"`
+	// Params is opaque JSON passed to the action.
+	Params json.RawMessage `json:"params,omitempty"`
+	// When, if set, names a registered predicate; the step is skipped when it
+	// returns false.
+	When string `json:"when,omitempty"`
+	// Hooks fire around the action.
+	Hooks Hooks `json:"hooks,omitempty"`
+	// Compensate, if set, is the action used to undo this step when a later step
+	// fails (executed in reverse order during rollback).
+	Compensate *ActionRef `json:"compensate,omitempty"`
+	// ContinueOnError records the error and proceeds instead of rolling back.
+	ContinueOnError bool `json:"continueOnError,omitempty"`
+}
+
+// ActionRef names an action and its params (used for compensation).
+type ActionRef struct {
+	Action string          `json:"action"`
+	Params json.RawMessage `json:"params,omitempty"`
+}
+
+// Hooks groups the hook references that fire at each phase of a step.
+type Hooks struct {
+	Before  []HookRef `json:"before,omitempty"`
+	After   []HookRef `json:"after,omitempty"`
+	OnError []HookRef `json:"onError,omitempty"`
+}
+
+// HookRef names a registered hook and its params.
+type HookRef struct {
+	Type   string          `json:"type"`
+	Params json.RawMessage `json:"params,omitempty"`
+}
+
+// Parse loads a flow definition from JSON bytes.
+func Parse(data []byte) (*Definition, error) {
+	var d Definition
+	if err := json.Unmarshal(data, &d); err != nil {
+		return nil, err
+	}
+	return &d, nil
+}