feat(runs): workflow drafts, publish with an expected version, delete, enabled flag, run on demand, run stages and statistics (#2061, #2113, #2098)

A disabled workflow is never started by a trigger, another workflow or a
person. Delete is refused while a trigger, another workflow or a run in
progress names it. A parked or ended run restarts from a step.
This commit is contained in:
sam committed 2026-11-22 11:34:49 +11:00
1 parent 9c0d043b57
commit 682995bdf7
15 files changed
+1552 -59

No files matched your search

+390 -3
View File
@@ -2457,6 +2457,21 @@ components:
required:
- body
type: object
PutDraftInputBody:
additionalProperties: false
properties:
body:
description: The draft document, as YAML. It may be unfinished or invalid; publishing checks it.
type: string
revision:
description: The revision of the draft as last read, 0 when there is none; the write is refused with 409 when the stored draft is at another
format: int64
minimum: 0
type: integer
required:
- body
- revision
type: object
PutKeyFieldsInputBody:
additionalProperties: false
properties:
@@ -2528,6 +2543,11 @@ components:
body:
description: The workflow document, as YAML
type: string
expected_version:
description: The latest version the document was edited from, 0 for a new workflow; the save is refused with 409 when another is stored
format: int64
minimum: 0
type: integer
required:
- body
type: object
@@ -2607,6 +2627,14 @@ components:
required:
- version
type: object
RunWorkflowInputBody:
additionalProperties: false
properties:
input:
additionalProperties: {}
description: The workflow's inputs by name
type: object
type: object
RunsActionTrail:
additionalProperties: false
properties:
@@ -2621,6 +2649,32 @@ components:
required:
- decision
type: object
RunsDraftView:
additionalProperties: false
properties:
base_version:
format: int64
type: integer
body:
type: string
name:
type: string
revision:
format: int64
type: integer
updated_at:
format: date-time
type: string
updated_by:
type: string
required:
- name
- body
- base_version
- revision
- updated_by
- updated_at
type: object
RunsDryAction:
additionalProperties: false
properties:
@@ -2703,6 +2757,21 @@ components:
- state
- at
type: object
RunsLastRun:
additionalProperties: false
properties:
at:
format: date-time
type: string
id:
type: string
state:
type: string
required:
- id
- state
- at
type: object
RunsOrigin:
additionalProperties: false
properties:
@@ -2764,6 +2833,8 @@ components:
type: string
detail:
type: string
dry:
type: boolean
error:
type: string
finished_at:
@@ -2789,6 +2860,32 @@ components:
- attempts
- created_at
type: object
RunsStage:
additionalProperties: false
properties:
ended_at:
format: date-time
type:
- string
- "null"
error:
type: string
name:
type: string
started_at:
format: date-time
type:
- string
- "null"
state:
type: string
type:
type: string
required:
- name
- type
- state
type: object
RunsStepType:
additionalProperties: false
properties:
@@ -2826,6 +2923,8 @@ components:
type:
- array
- "null"
definition:
type: string
entries:
items:
$ref: "#/components/schemas/RunsTrailEntry"
@@ -2836,8 +2935,15 @@ components:
$ref: "#/components/schemas/RunsOrigin"
run:
$ref: "#/components/schemas/RunsRunView"
stages:
items:
$ref: "#/components/schemas/RunsStage"
type:
- array
- "null"
required:
- run
- stages
- actions
- entries
type: object
@@ -2865,6 +2971,8 @@ components:
seq:
format: int64
type: integer
step:
type: string
text:
type: string
tool_calls:
@@ -2883,6 +2991,38 @@ components:
- at
- kind
type: object
RunsWorkflowStats:
additionalProperties: false
properties:
active:
format: int64
type: integer
failed:
format: int64
type: integer
last_run:
$ref: "#/components/schemas/RunsLastRun"
succeeded:
format: int64
type: integer
success_rate:
format: double
type:
- number
- "null"
total:
format: int64
type: integer
workflow:
type: string
required:
- workflow
- total
- succeeded
- failed
- active
- last_run
type: object
RunsWorkflowView:
additionalProperties: false
properties:
@@ -2893,6 +3033,8 @@ components:
type: string
created_by:
type: string
enabled:
type: boolean
name:
type: string
steps:
@@ -2911,6 +3053,7 @@ components:
- created_by
- created_at
- steps
- enabled
type: object
Schema:
additionalProperties: false
@@ -3100,6 +3243,14 @@ components:
required:
- text
type: object
SetEnabledInputBody:
additionalProperties: false
properties:
enabled:
type: boolean
required:
- enabled
type: object
SetMemberInputBody:
additionalProperties: false
properties:
@@ -6095,7 +6246,7 @@ paths:
schema:
$ref: "#/components/schemas/ErrorModel"
description: Error
summary: Retry a parked run from a step, keeping the results of the steps before it
summary: Restart a parked or ended run from a step, keeping the results of the steps before it
tags:
- Runs
/api/secret-engines:
@@ -6659,6 +6810,52 @@ paths:
summary: Add or change a trigger
tags:
- Events
/api/workflow-drafts:
get:
operationId: list-workflow-drafts
responses:
"200":
content:
application/json:
schema:
items:
$ref: "#/components/schemas/RunsDraftView"
type:
- array
- "null"
description: OK
default:
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ErrorModel"
description: Error
summary: List every workflow's unpublished draft
tags:
- Workflows
/api/workflow-stats:
get:
operationId: list-workflow-stats
responses:
"200":
content:
application/json:
schema:
items:
$ref: "#/components/schemas/RunsWorkflowStats"
type:
- array
- "null"
description: OK
default:
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ErrorModel"
description: Error
summary: Count each workflow's runs, with its last run and success rate
tags:
- Workflows
/api/workflow-step-types:
get:
operationId: list-workflow-step-types
@@ -6679,7 +6876,7 @@ paths:
schema:
$ref: "#/components/schemas/ErrorModel"
description: Error
summary: List the step types a workflow document may name, with their settings schemas
summary: List the step types a workflow document may name, with their titles and settings schemas
tags:
- Workflows
/api/workflows:
@@ -6706,6 +6903,26 @@ paths:
tags:
- Workflows
/api/workflows/{name}:
delete:
operationId: delete-workflow
parameters:
- in: path
name: name
required: true
schema:
type: string
responses:
"204":
description: No Content
default:
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ErrorModel"
description: Error
summary: Delete a workflow, unless a trigger or another workflow still names it
tags:
- Workflows
get:
operationId: get-workflow
parameters:
@@ -6768,7 +6985,177 @@ paths:
schema:
$ref: "#/components/schemas/ErrorModel"
description: Error
summary: Save a workflow document as its next version
summary: Publish a workflow document as its next version
tags:
- Workflows
/api/workflows/{name}/draft:
delete:
operationId: discard-workflow-draft
parameters:
- in: path
name: name
required: true
schema:
type: string
responses:
"204":
description: No Content
default:
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ErrorModel"
description: Error
summary: Discard a workflow's draft
tags:
- Workflows
get:
operationId: get-workflow-draft
parameters:
- in: path
name: name
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/RunsDraftView"
description: OK
default:
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ErrorModel"
description: Error
summary: Get a workflow's unpublished draft
tags:
- Workflows
put:
operationId: put-workflow-draft
parameters:
- description: Lowercase letters and digits, joined by dots or hyphens
in: path
name: name
required: true
schema:
description: Lowercase letters and digits, joined by dots or hyphens
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/PutDraftInputBody"
required: true
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/RunsDraftView"
description: OK
default:
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ErrorModel"
description: Error
summary: Save a workflow's draft, which no run uses until it is published
tags:
- Workflows
/api/workflows/{name}/draft/test-run:
post:
operationId: test-workflow-draft
parameters:
- in: path
name: name
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/RunWorkflowInputBody"
required: true
responses:
"202":
content:
application/json:
schema:
$ref: "#/components/schemas/RunsRunView"
description: Accepted
default:
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ErrorModel"
description: Error
summary: "Test-run a workflow's draft: every action is judged and none that changes something runs"
tags:
- Workflows
/api/workflows/{name}/enabled:
put:
operationId: set-workflow-enabled
parameters:
- in: path
name: name
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/SetEnabledInputBody"
required: true
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/RunsWorkflowView"
description: OK
default:
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ErrorModel"
description: Error
summary: Enable or disable a workflow
tags:
- Workflows
/api/workflows/{name}/runs:
post:
operationId: run-workflow
parameters:
- in: path
name: name
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/RunWorkflowInputBody"
required: true
responses:
"202":
content:
application/json:
schema:
$ref: "#/components/schemas/RunsRunView"
description: Accepted
default:
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ErrorModel"
description: Error
summary: Run a workflow now with an input
tags:
- Workflows
/oauth2/callback:
+1
View File
@@ -193,6 +193,7 @@ func wire(log *slog.Logger, configPath string, cfg Config, db *sqlx.DB) (*binary
}
hear := events.NewModule(db, log.With("module", "events"), orgID, sealer, conns, engine, allow, settings, tell)
hear.Routes(mux)
engine.UseReferrers(hear)
judge := newJudgement(db, log, conns, classes, policies, settings, hear)
// The record of deletions outlives this process and its database, so the
// log exists before anything can be deleted: an instance that has run this
@@ -0,0 +1,29 @@
-- +goose Up
-- A draft is the unpublished edit of a workflow, kept so work survives a reload
-- and never reaches a run until it is published as the next version. revision
-- counts writes: a write that names an older one is refused, so two editors
-- can't overwrite each other. base_version is the published version the draft
-- began from; a new workflow's is 0.
CREATE TABLE runs.workflow_drafts (
org_id text NOT NULL,
name text NOT NULL,
body text NOT NULL,
base_version integer NOT NULL,
revision integer NOT NULL DEFAULT 1,
updated_by text NOT NULL,
updated_at timestamptz NOT NULL DEFAULT now(),
PRIMARY KEY (org_id, name)
);
-- A workflow with no row here is enabled. A disabled workflow is never started,
-- by a trigger, by another workflow or on demand.
CREATE TABLE runs.workflow_settings (
org_id text NOT NULL,
name text NOT NULL,
enabled boolean NOT NULL,
PRIMARY KEY (org_id, name)
);
-- +goose Down
DROP TABLE runs.workflow_settings;
DROP TABLE runs.workflow_drafts;
+4
View File
@@ -536,6 +536,10 @@ func (m *Module) startRun(ctx context.Context, e store.Event, t store.Trigger) (
m.log.WarnContext(ctx, "trigger not permitted to start its workflow", "event", e.ID, "trigger", t.Name, "error", err)
return uuid.Nil, false, nil
}
if errors.Is(err, runs.ErrDisabled) {
m.log.InfoContext(ctx, "trigger skipped: its workflow is disabled", "event", e.ID, "trigger", t.Name, "workflow", t.Workflow)
return uuid.Nil, false, nil
}
if err != nil {
return uuid.Nil, false, fmt.Errorf("start run for trigger %q: %w", t.Name, err)
}
+18
View File
@@ -0,0 +1,18 @@
package events
import "context"
// WorkflowTriggers names the triggers that start workflow.
func (m *Module) WorkflowTriggers(ctx context.Context, workflow string) ([]string, error) {
triggers, err := m.store.AllTriggers(ctx, m.orgID)
if err != nil {
return nil, err
}
var names []string
for _, t := range triggers {
if t.Workflow == workflow {
names = append(names, t.Name)
}
}
return names, nil
}
+191
View File
@@ -0,0 +1,191 @@
package runs
import (
"context"
"errors"
"fmt"
"slices"
"strings"
"github.com/samcharles93/archie-core/modules/runs/internal/store"
)
// definitions is the stored workflows and drafts the catalogue operations read
// and change.
type definitions interface {
Workflow(ctx context.Context, orgID, name string, version int) (store.Workflow, error)
Workflows(ctx context.Context, orgID string) ([]store.Workflow, error)
AddWorkflow(ctx context.Context, orgID, name, body, by string, expected *int) (store.Workflow, error)
SetEnabled(ctx context.Context, orgID, name string, enabled bool) error
DeleteWorkflow(ctx context.Context, orgID, name string) error
DeleteDraft(ctx context.Context, orgID, name string) (bool, error)
ActiveRuns(ctx context.Context, orgID, name string) (int, error)
}
// Referrers finds what outside the runs module names a workflow.
type Referrers interface {
// WorkflowTriggers names the triggers that start the workflow.
WorkflowTriggers(ctx context.Context, workflow string) ([]string, error)
}
// UseReferrers tells the engine where to look for the triggers that start a
// workflow. It must be called before the API is served.
func (e *Engine) UseReferrers(r Referrers) {
e.mu.Lock()
defer e.mu.Unlock()
e.referrers = r
}
var (
// ErrVersionConflict is returned by Publish when the workflow's latest
// version is not the one the caller expected.
ErrVersionConflict = store.ErrVersionConflict
// ErrDisabled is returned when a start names a disabled workflow.
ErrDisabled = errors.New("the workflow is disabled")
// ErrNoWorkflow is returned when no workflow has the name.
ErrNoWorkflow = store.ErrNoWorkflow
)
// refusal is a start the workflow can't take as asked: its inputs are wrong or
// it can't run yet. It is the caller's to fix, unlike a failure to reach storage.
type refusal struct{ error }
func (r refusal) Unwrap() error { return r.error }
// IsRefusal reports whether err says a run can't start as asked.
func IsRefusal(err error) bool {
_, ok := errors.AsType[refusal](err)
return ok
}
// ReferencedError says what keeps a workflow from being deleted.
type ReferencedError struct {
Workflow string
// By names each trigger, workflow or run that still depends on it.
By []string
}
func (e *ReferencedError) Error() string {
return fmt.Sprintf("workflow %q is still used by %s", e.Workflow, strings.Join(e.By, ", "))
}
// Publish stores body as the next version of the workflow name and discards
// its draft. When expected is set, the latest version must be that one (zero
// for a workflow not yet published), or the body is not stored. A body that
// doesn't validate is stored as nothing.
func (e *Engine) Publish(ctx context.Context, orgID, name, body, by string, expected *int) (int, error) {
if _, err := e.validateDocument(ctx, body); err != nil {
return 0, err
}
return e.publish(ctx, orgID, name, body, by, expected)
}
func (e *Engine) publish(ctx context.Context, orgID, name, body, by string, expected *int) (int, error) {
latest, err := e.defs.Workflow(ctx, orgID, name, 0)
if err != nil && !errors.Is(err, store.ErrNoWorkflow) {
return 0, err
}
if expected != nil && latest.Version != *expected {
return 0, ErrVersionConflict
}
version := latest.Version
if version == 0 || normalise(latest.Body) != normalise(body) {
w, err := e.defs.AddWorkflow(ctx, orgID, name, body, by, expected)
if err != nil {
return 0, err
}
version = w.Version
}
if _, err := e.defs.DeleteDraft(ctx, orgID, name); err != nil {
e.log.WarnContext(ctx, "discard published draft", "workflow", name, "error", err)
}
return version, nil
}
// SetEnabled enables or disables a workflow. A disabled workflow is not
// started by a trigger, another workflow or a person.
func (e *Engine) SetEnabled(ctx context.Context, orgID, name string, enabled bool) error {
return e.defs.SetEnabled(ctx, orgID, name, enabled)
}
// Delete removes a workflow with all its versions and its draft. It is refused,
// naming what depends on the workflow, while a trigger or another workflow
// names it or one of its runs is still going.
func (e *Engine) Delete(ctx context.Context, orgID, name string) error {
if _, err := e.defs.Workflow(ctx, orgID, name, 0); err != nil {
return err
}
by, err := e.referencesTo(ctx, orgID, name)
if err != nil {
return err
}
if len(by) > 0 {
return &ReferencedError{Workflow: name, By: by}
}
return e.defs.DeleteWorkflow(ctx, orgID, name)
}
func (e *Engine) referencesTo(ctx context.Context, orgID, name string) ([]string, error) {
var by []string
e.mu.RLock()
referrers := e.referrers
e.mu.RUnlock()
if referrers != nil {
triggers, err := referrers.WorkflowTriggers(ctx, name)
if err != nil {
return nil, fmt.Errorf("find triggers of %q: %w", name, err)
}
for _, t := range triggers {
by = append(by, "trigger "+t)
}
}
all, err := e.defs.Workflows(ctx, orgID)
if err != nil {
return nil, err
}
for _, w := range all {
if w.Name == name {
continue
}
doc, err := ParseDocument(w.Body)
if err != nil {
continue
}
if slices.Contains(workflowsNamedIn(doc.Steps), name) {
by = append(by, "workflow "+w.Name)
}
}
active, err := e.defs.ActiveRuns(ctx, orgID, name)
if err != nil {
return nil, err
}
if active > 0 {
by = append(by, fmt.Sprintf("%d runs in progress", active))
}
return by, nil
}
// workflowsNamedIn lists the workflows steps call or hand off to, however
// deeply the steps are nested.
func workflowsNamedIn(steps []Step) []string {
var out []string
for _, s := range steps {
if s.Type == typeCall || s.Type == typeHandoff {
var named struct {
Workflow string `yaml:"workflow"`
}
if err := s.Settings.Decode(&named); err == nil && named.Workflow != "" {
out = append(out, named.Workflow)
}
}
for _, branch := range s.Parallel {
out = append(out, workflowsNamedIn(branch)...)
}
if s.Switch != nil {
for _, branch := range s.Switch.Cases {
out = append(out, workflowsNamedIn(branch)...)
}
}
}
return out
}
+203
View File
@@ -0,0 +1,203 @@
package runs
import (
"context"
"errors"
"log/slog"
"slices"
"testing"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/runs/internal/store"
)
// shelf is an in-memory set of stored workflows, drafts and runs in progress.
type shelf struct {
versions map[string][]string
drafts map[string]bool
active map[string]int
deleted []string
}
func (s *shelf) Workflow(_ context.Context, _, name string, _ int) (store.Workflow, error) {
v := s.versions[name]
if len(v) == 0 {
return store.Workflow{}, store.ErrNoWorkflow
}
return store.Workflow{Name: name, Version: len(v), Body: v[len(v)-1]}, nil
}
func (s *shelf) Workflows(ctx context.Context, org string) ([]store.Workflow, error) {
var out []store.Workflow
for name := range s.versions {
w, _ := s.Workflow(ctx, org, name, 0)
out = append(out, w)
}
return out, nil
}
// AddWorkflow stores unconditionally: the store's own check is SQL, so what is
// tested here is the check the engine makes before it.
func (s *shelf) AddWorkflow(_ context.Context, _, name, body, _ string, _ *int) (store.Workflow, error) {
s.versions[name] = append(s.versions[name], body)
return store.Workflow{Name: name, Version: len(s.versions[name]), Body: body}, nil
}
func (s *shelf) SetEnabled(context.Context, string, string, bool) error { return nil }
func (s *shelf) DeleteWorkflow(_ context.Context, _, name string) error {
delete(s.versions, name)
s.deleted = append(s.deleted, name)
return nil
}
func (s *shelf) DeleteDraft(_ context.Context, _, name string) (bool, error) {
had := s.drafts[name]
delete(s.drafts, name)
return had, nil
}
func (s *shelf) ActiveRuns(_ context.Context, _, name string) (int, error) {
return s.active[name], nil
}
type triggerNames map[string][]string
func (t triggerNames) WorkflowTriggers(_ context.Context, workflow string) ([]string, error) {
return t[workflow], nil
}
const notifyDoc = "steps:\n - type: run.notify\n"
// TestPublishRefusesAStaleVersion guards that an editor can't publish over a
// version it never saw: a publish that names a version other than the latest
// stores nothing and leaves the draft, while a publish of the version it was
// edited from is stored and consumes the draft. Without it two editors silently
// overwrite each other's published work.
func TestPublishRefusesAStaleVersion(t *testing.T) {
two, zero := 2, 0
tests := []struct {
name string
stored []string
expected *int
body string
wantVersions int
wantDraft bool
wantErr error
}{
{name: "an unconditional publish", stored: []string{"a", "b"}, body: "c", wantVersions: 3},
{name: "the version it was edited from", stored: []string{"a", "b"}, expected: &two, body: "c", wantVersions: 3},
{name: "a stale version", stored: []string{"a", "b", "c"}, expected: &two, body: "d", wantVersions: 3, wantDraft: true, wantErr: ErrVersionConflict},
{name: "a new workflow that now exists", stored: []string{"a"}, expected: &zero, body: "b", wantVersions: 1, wantDraft: true, wantErr: ErrVersionConflict},
{name: "a new workflow", expected: &zero, body: "a", wantVersions: 1},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
s := &shelf{versions: map[string][]string{}, drafts: map[string]bool{"triage": true}}
if tt.stored != nil {
s.versions["triage"] = tt.stored
}
e := &Engine{defs: s, log: slog.New(slog.DiscardHandler)}
_, err := e.publish(t.Context(), "org", "triage", tt.body, "admin", tt.expected)
if !errors.Is(err, tt.wantErr) {
t.Fatalf("error = %v, want %v", err, tt.wantErr)
}
if got := len(s.versions["triage"]); got != tt.wantVersions {
t.Fatalf("versions stored = %d, want %d", got, tt.wantVersions)
}
if s.drafts["triage"] != tt.wantDraft {
t.Fatalf("draft kept = %v, want %v", s.drafts["triage"], tt.wantDraft)
}
})
}
}
// TestDisabledWorkflowIsNeverStarted guards that a disabled workflow starts
// from no door: a trigger and a person both start through Start, and a call
// from another workflow resolves through newRun. Without it disabling a
// workflow would only hide it.
func TestDisabledWorkflowIsNeverStarted(t *testing.T) {
tests := []struct {
name string
disabled bool
viaCall bool
wantErr error
want int
}{
{name: "an enabled workflow starts", want: 1},
{name: "a trigger or a person can't start a disabled one", disabled: true, wantErr: ErrDisabled},
{name: "a call can't start a disabled one", disabled: true, viaCall: true, wantErr: ErrDisabled},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
work := &queueingStore{}
work.disabled = map[string]bool{"triage": tt.disabled}
engine := newEngine(nil, work, slog.New(slog.DiscardHandler), Options{})
engine.queue = work
engine.Use(Deps{Access: &recordingAccess{decision: governance.Allowed()}})
req := StartRequest{OrgID: "org", Workflow: "triage", Key: "event:trigger"}
var err error
if tt.viaCall {
_, err = newRun(t.Context(), work, req)
} else {
ctx := governance.WithPrincipal(t.Context(), governance.WorkloadPrincipal(governance.DefaultOrgID))
_, err = engine.Start(ctx, req)
}
if !errors.Is(err, tt.wantErr) {
t.Fatalf("error = %v, want %v", err, tt.wantErr)
}
if len(work.queued) != tt.want {
t.Fatalf("runs queued = %d, want %d", len(work.queued), tt.want)
}
})
}
}
// TestDeleteIsRefusedWhileReferenced guards that a workflow nothing depends on
// is deleted, and one a trigger, another workflow (at any depth) or a run in
// progress depends on is refused with each dependant named. Without it a
// delete leaves triggers and calls that fail on their next use.
func TestDeleteIsRefusedWhileReferenced(t *testing.T) {
calls := "steps:\n - type: workflow.call\n settings: {workflow: triage}\n"
tests := []struct {
name string
others map[string][]string
triggers triggerNames
active int
wantBy []string
}{
{name: "nothing depends on it"},
{name: "a trigger", triggers: triggerNames{"triage": {"alerts"}}, wantBy: []string{"trigger alerts"}},
{name: "another workflow's call", others: map[string][]string{"parent": {calls}}, wantBy: []string{"workflow parent"}},
{name: "a run in progress", active: 2, wantBy: []string{"2 runs in progress"}},
{
name: "a trigger and a workflow", triggers: triggerNames{"triage": {"alerts"}},
others: map[string][]string{"parent": {calls}}, wantBy: []string{"trigger alerts", "workflow parent"},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
s := &shelf{versions: map[string][]string{"triage": {notifyDoc}}, drafts: map[string]bool{}, active: map[string]int{"triage": tt.active}}
for name, v := range tt.others {
s.versions[name] = v
}
e := &Engine{defs: s, log: slog.New(slog.DiscardHandler), referrers: tt.triggers}
err := e.Delete(t.Context(), "org", "triage")
var refs *ReferencedError
if len(tt.wantBy) == 0 {
if err != nil || !slices.Equal(s.deleted, []string{"triage"}) {
t.Fatalf("delete = %v, deleted %v, want it deleted", err, s.deleted)
}
return
}
if !errors.As(err, &refs) || !slices.Equal(refs.By, tt.wantBy) {
t.Fatalf("error = %v, want a refusal naming %v", err, tt.wantBy)
}
if len(s.deleted) != 0 {
t.Fatalf("deleted %v despite the refusal", s.deleted)
}
})
}
}
+9 -2
View File
@@ -32,6 +32,13 @@ func (o *dryOverlay) policy() *judgement.PolicyOverlay {
return &judgement.PolicyOverlay{Kind: o.PolicyKind, Body: o.Policy}
}
func (o *dryOverlay) documentOr() string {
if o == nil {
return ""
}
return o.Document
}
func readOverlay(raw jsontext.Value) (*dryOverlay, error) {
var o dryOverlay
if err := json.Unmarshal(raw, &o); err != nil {
@@ -83,7 +90,7 @@ func (e *Engine) StartDry(ctx context.Context, req DryRequest) (uuid.UUID, error
// A dry run starts like a live one: a document that can't start can't be
// tested, and its inputs are checked the same way.
if err := doc.unsupported(); err != nil {
return uuid.Nil, err
return uuid.Nil, refusal{err}
}
overlay, err := json.Marshal(dryOverlay{Document: req.Document, PolicyKind: req.PolicyKind, Policy: req.Policy})
if err != nil {
@@ -94,7 +101,7 @@ func (e *Engine) StartDry(ctx context.Context, req DryRequest) (uuid.UUID, error
input = jsontext.Value("null")
}
if err := doc.checkInputs(decodeInputs(input)); err != nil {
return uuid.Nil, fmt.Errorf("workflow %q: %w", req.Workflow, err)
return uuid.Nil, refusal{fmt.Errorf("workflow %q: %w", req.Workflow, err)}
}
return e.queue.Start(ctx, store.NewRun{
OrgID: req.OrgID, Workflow: req.Workflow, Input: input, Dry: true, Overlay: overlay,
+14 -6
View File
@@ -8,6 +8,7 @@ import (
"encoding/json/jsontext"
"errors"
"fmt"
"slices"
"time"
"github.com/google/uuid"
@@ -50,8 +51,9 @@ var (
ErrStepExists = errors.New("step already recorded")
// ErrNoRun means the organisation has no such run to retry.
ErrNoRun = errors.New("no such run")
// ErrNotParked means the run is not parked, so there is nothing to retry.
ErrNotParked = errors.New("run is not parked")
// ErrNotEnded means the run is still going, or was cancelled, so it has no
// step to restart from.
ErrNotEnded = errors.New("run has not ended")
// ErrNoStep means the run never reached the step it was to retry from.
ErrNoStep = errors.New("run did not reach that step")
// ErrEnded means the run has already ended, so there is nothing to cancel.
@@ -322,7 +324,11 @@ func signalParent(ctx context.Context, q execer, id uuid.UUID) error {
return nil
}
// Retry queues a parked run to run again from a step, keeping what the steps
// restartable are the states a run may be restarted from: it has ended, or it
// is parked for an operator.
var restartable = []string{StateParked, StateFailed, StateSucceeded, StateDeclined}
// Retry queues an ended or parked run to run again from a step, keeping what the steps
// before it recorded: the run replays them without repeating their effects.
// from names the step; empty means the step the run last reached. What that
// step and every later one recorded is forgotten, including the markers that
@@ -340,8 +346,8 @@ func (s *Store) Retry(ctx context.Context, orgID string, id uuid.UUID, from stri
return ErrNoRun
case err != nil:
return fmt.Errorf("retry run: %w", err)
case state != StateParked:
return ErrNotParked
case !slices.Contains(restartable, state):
return ErrNotEnded
}
var at struct {
Marker int `db:"marker"`
@@ -505,6 +511,8 @@ type Detail struct {
Summary
Input jsontext.Value `db:"input"`
Result jsontext.Value `db:"result"`
// Overlay is the document a dry run executes; a live run has none.
Overlay []byte `db:"overlay"`
}
// Recorded is a step with the time it was recorded.
@@ -530,7 +538,7 @@ func (s *Store) Detail(ctx context.Context, orgID string, id uuid.UUID) (Detail,
var d Detail
err := s.db.GetContext(ctx, &d, `
SELECT id, workflow, workflow_version, state, attempts, error, detail, created_at, finished_at, dry, input,
coalesce(result, 'null') AS result
coalesce(result, 'null') AS result, overlay
FROM runs.runs WHERE org_id = $1 AND id = $2`, orgID, id)
if errors.Is(err, sql.ErrNoRows) {
return Detail{}, false, nil
+191 -9
View File
@@ -8,8 +8,18 @@ import (
"time"
)
// ErrNoWorkflow means no workflow is stored under that name and version.
var ErrNoWorkflow = errors.New("no such workflow")
var (
// ErrNoWorkflow means no workflow is stored under that name and version.
ErrNoWorkflow = errors.New("no such workflow")
// ErrVersionConflict means the workflow's latest version is not the one
// the writer expected.
ErrVersionConflict = errors.New("the workflow has another version than expected")
// ErrDraftConflict means the stored draft is not the revision the writer
// last saw.
ErrDraftConflict = errors.New("the draft changed since it was read")
// ErrNoDraft means the workflow has no draft.
ErrNoDraft = errors.New("no such draft")
)
// Workflow is one stored version of a workflow document.
type Workflow struct {
@@ -18,15 +28,20 @@ type Workflow struct {
Body string `db:"body"`
CreatedBy string `db:"created_by"`
CreatedAt time.Time `db:"created_at"`
// Disabled is a workflow nothing may start. The zero value is enabled.
Disabled bool `db:"disabled"`
}
const workflowColumns = `w.name, w.version, w.body, w.created_by, w.created_at, COALESCE(NOT s.enabled, false) AS disabled`
// Workflow returns a version of a workflow, or its latest when version is zero.
func (s *Store) Workflow(ctx context.Context, orgID, name string, version int) (Workflow, error) {
var w Workflow
err := s.db.GetContext(ctx, &w, `
SELECT name, version, body, created_by, created_at FROM runs.workflows
WHERE org_id = $1 AND name = $2 AND ($3 = 0 OR version = $3)
ORDER BY version DESC LIMIT 1`, orgID, name, version)
SELECT `+workflowColumns+` FROM runs.workflows w
LEFT JOIN runs.workflow_settings s ON s.org_id = w.org_id AND s.name = w.name
WHERE w.org_id = $1 AND w.name = $2 AND ($3 = 0 OR w.version = $3)
ORDER BY w.version DESC LIMIT 1`, orgID, name, version)
if errors.Is(err, sql.ErrNoRows) {
return Workflow{}, ErrNoWorkflow
}
@@ -40,22 +55,189 @@ func (s *Store) Workflow(ctx context.Context, orgID, name string, version int) (
func (s *Store) Workflows(ctx context.Context, orgID string) ([]Workflow, error) {
var out []Workflow
if err := s.db.SelectContext(ctx, &out, `
SELECT DISTINCT ON (name) name, version, body, created_by, created_at FROM runs.workflows
WHERE org_id = $1 ORDER BY name, version DESC`, orgID); err != nil {
SELECT DISTINCT ON (w.name) `+workflowColumns+` FROM runs.workflows w
LEFT JOIN runs.workflow_settings s ON s.org_id = w.org_id AND s.name = w.name
WHERE w.org_id = $1 ORDER BY w.name, w.version DESC`, orgID); err != nil {
return nil, fmt.Errorf("list workflows: %w", err)
}
return out, nil
}
// AddWorkflow stores body as the next version of a workflow and returns it.
func (s *Store) AddWorkflow(ctx context.Context, orgID, name, body, by string) (Workflow, error) {
// When expected is given, the workflow's latest version must be that one (zero
// for a workflow with none), or nothing is stored.
func (s *Store) AddWorkflow(ctx context.Context, orgID, name, body, by string, expected *int) (Workflow, error) {
var want sql.NullInt64
if expected != nil {
want = sql.NullInt64{Int64: int64(*expected), Valid: true}
}
var w Workflow
err := s.db.GetContext(ctx, &w, `
INSERT INTO runs.workflows (org_id, name, version, body, created_by)
SELECT $1, $2, COALESCE(max(version), 0) + 1, $3, $4 FROM runs.workflows WHERE org_id = $1 AND name = $2
RETURNING name, version, body, created_by, created_at`, orgID, name, body, by)
HAVING $5::bigint IS NULL OR COALESCE(max(version), 0) = $5
RETURNING name, version, body, created_by, created_at, false AS disabled`, orgID, name, body, by, want)
if errors.Is(err, sql.ErrNoRows) {
return Workflow{}, ErrVersionConflict
}
if err != nil {
return Workflow{}, fmt.Errorf("store workflow: %w", err)
}
return w, nil
}
// SetEnabled enables or disables a stored workflow.
func (s *Store) SetEnabled(ctx context.Context, orgID, name string, enabled bool) error {
res, err := s.db.ExecContext(ctx, `
INSERT INTO runs.workflow_settings (org_id, name, enabled)
SELECT $1, $2, $3 WHERE EXISTS (SELECT 1 FROM runs.workflows WHERE org_id = $1 AND name = $2)
ON CONFLICT (org_id, name) DO UPDATE SET enabled = EXCLUDED.enabled`, orgID, name, enabled)
if err != nil {
return fmt.Errorf("set workflow enabled: %w", err)
}
if affected(res) == 0 {
return ErrNoWorkflow
}
return nil
}
// DeleteWorkflow removes every version of a workflow with its draft and
// settings. The runs it made keep their record.
func (s *Store) DeleteWorkflow(ctx context.Context, orgID, name string) error {
tx, err := s.db.BeginTxx(ctx, nil)
if err != nil {
return fmt.Errorf("delete workflow: %w", err)
}
defer func() { _ = tx.Rollback() }()
res, err := tx.ExecContext(ctx, `DELETE FROM runs.workflows WHERE org_id = $1 AND name = $2`, orgID, name)
if err != nil {
return fmt.Errorf("delete workflow: %w", err)
}
if affected(res) == 0 {
return ErrNoWorkflow
}
if _, err := tx.ExecContext(ctx, `DELETE FROM runs.workflow_drafts WHERE org_id = $1 AND name = $2`, orgID, name); err != nil {
return fmt.Errorf("delete workflow draft: %w", err)
}
if _, err := tx.ExecContext(ctx, `DELETE FROM runs.workflow_settings WHERE org_id = $1 AND name = $2`, orgID, name); err != nil {
return fmt.Errorf("delete workflow settings: %w", err)
}
if err := tx.Commit(); err != nil {
return fmt.Errorf("delete workflow: %w", err)
}
return nil
}
// Draft is the unpublished edit of a workflow.
type Draft struct {
Name string `db:"name"`
Body string `db:"body"`
BaseVersion int `db:"base_version"`
Revision int `db:"revision"`
UpdatedBy string `db:"updated_by"`
UpdatedAt time.Time `db:"updated_at"`
}
const draftColumns = `name, body, base_version, revision, updated_by, updated_at`
// Draft returns a workflow's draft.
func (s *Store) Draft(ctx context.Context, orgID, name string) (Draft, error) {
var d Draft
err := s.db.GetContext(ctx, &d, `SELECT `+draftColumns+` FROM runs.workflow_drafts WHERE org_id = $1 AND name = $2`, orgID, name)
if errors.Is(err, sql.ErrNoRows) {
return Draft{}, ErrNoDraft
}
if err != nil {
return Draft{}, fmt.Errorf("read draft: %w", err)
}
return d, nil
}
// Drafts returns every workflow's draft.
func (s *Store) Drafts(ctx context.Context, orgID string) ([]Draft, error) {
var out []Draft
if err := s.db.SelectContext(ctx, &out, `SELECT `+draftColumns+` FROM runs.workflow_drafts WHERE org_id = $1 ORDER BY name`, orgID); err != nil {
return nil, fmt.Errorf("list drafts: %w", err)
}
return out, nil
}
// PutDraft writes a workflow's draft. revision is the one the writer last saw,
// zero for a workflow with no draft; a draft at any other revision is not
// overwritten.
func (s *Store) PutDraft(ctx context.Context, orgID, name, body, by string, revision int) (Draft, error) {
var d Draft
var err error
if revision == 0 {
err = s.db.GetContext(ctx, &d, `
INSERT INTO runs.workflow_drafts (org_id, name, body, base_version, updated_by)
SELECT $1, $2, $3, COALESCE(max(version), 0), $4 FROM runs.workflows WHERE org_id = $1 AND name = $2
ON CONFLICT (org_id, name) DO NOTHING
RETURNING `+draftColumns, orgID, name, body, by)
} else {
err = s.db.GetContext(ctx, &d, `
UPDATE runs.workflow_drafts SET body = $3, revision = revision + 1, updated_by = $4, updated_at = now()
WHERE org_id = $1 AND name = $2 AND revision = $5
RETURNING `+draftColumns, orgID, name, body, by, revision)
}
if errors.Is(err, sql.ErrNoRows) {
return Draft{}, ErrDraftConflict
}
if err != nil {
return Draft{}, fmt.Errorf("write draft: %w", err)
}
return d, nil
}
// DeleteDraft discards a workflow's draft, and reports whether it had one.
func (s *Store) DeleteDraft(ctx context.Context, orgID, name string) (bool, error) {
res, err := s.db.ExecContext(ctx, `DELETE FROM runs.workflow_drafts WHERE org_id = $1 AND name = $2`, orgID, name)
if err != nil {
return false, fmt.Errorf("delete draft: %w", err)
}
return affected(res) > 0, nil
}
// Stats is what a workflow's runs add up to. Dry runs are not counted.
type Stats struct {
Workflow string `db:"workflow"`
Total int `db:"total"`
Succeeded int `db:"succeeded"`
// Failed counts runs that failed, parked or were declined.
Failed int `db:"failed"`
// Active counts runs that haven't ended.
Active int `db:"active"`
LastRunID string `db:"last_run_id"`
LastState string `db:"last_state"`
LastRunAt time.Time `db:"last_run_at"`
}
// Stats returns each workflow's run statistics over all of its runs.
func (s *Store) Stats(ctx context.Context, orgID string) ([]Stats, error) {
var out []Stats
if err := s.db.SelectContext(ctx, &out, `
SELECT workflow,
count(*) AS total,
count(*) FILTER (WHERE state = 'succeeded') AS succeeded,
count(*) FILTER (WHERE state IN ('failed', 'parked', 'declined')) AS failed,
count(*) FILTER (WHERE state IN ('queued', 'running', 'waiting', 'waiting_approval')) AS active,
(array_agg(id::text ORDER BY created_at DESC))[1] AS last_run_id,
(array_agg(state ORDER BY created_at DESC))[1] AS last_state,
max(created_at) AS last_run_at
FROM runs.runs WHERE org_id = $1 AND NOT dry
GROUP BY workflow ORDER BY workflow`, orgID); err != nil {
return nil, fmt.Errorf("count workflow runs: %w", err)
}
return out, nil
}
// ActiveRuns counts a workflow's runs that haven't ended.
func (s *Store) ActiveRuns(ctx context.Context, orgID, name string) (int, error) {
var n int
if err := s.db.GetContext(ctx, &n, `
SELECT count(*) FROM runs.runs
WHERE org_id = $1 AND workflow = $2 AND NOT dry AND state IN ('queued', 'running', 'waiting', 'waiting_approval')`, orgID, name); err != nil {
return 0, fmt.Errorf("count active runs: %w", err)
}
return n, nil
}
+13 -20
View File
@@ -66,6 +66,8 @@ type runStarter interface {
// Engine starts, executes and resumes runs.
type Engine struct {
db *store.Store
// defs is the stored workflows; it is db except in tests.
defs definitions
// queue starts runs; it is db except in tests.
queue runQueue
work runWork
@@ -73,6 +75,8 @@ type Engine struct {
opts Options
mu sync.RWMutex
deps *Deps
// referrers finds the triggers that name a workflow.
referrers Referrers
// claimFailure is the last failed attempt to claim a run, cleared by the
// next attempt that succeeds.
claimFailure atomic.Pointer[claimFailure]
@@ -99,7 +103,7 @@ func newEngine(db *store.Store, work runWork, log *slog.Logger, opts Options) *E
if opts.Owner == "" {
opts.Owner = "archie"
}
e := &Engine{db: db, queue: db, work: work, log: log, opts: opts}
e := &Engine{db: db, defs: db, queue: db, work: work, log: log, opts: opts}
e.load = e.loadDocument
return e
}
@@ -126,21 +130,7 @@ func (e *Engine) steps() (Deps, error) {
// what the latest version already is, and returns the version in force. A body
// that doesn't validate is stored as nothing.
func (e *Engine) Install(ctx context.Context, orgID, name, body, by string) (int, error) {
if _, err := e.validateDocument(ctx, body); err != nil {
return 0, err
}
latest, err := e.db.Workflow(ctx, orgID, name, 0)
switch {
case err == nil && normalise(latest.Body) == normalise(body):
return latest.Version, nil
case err != nil && !errors.Is(err, store.ErrNoWorkflow):
return 0, err
}
w, err := e.db.AddWorkflow(ctx, orgID, name, body, by)
if err != nil {
return 0, err
}
return w.Version, nil
return e.Publish(ctx, orgID, name, body, by, nil)
}
func (e *Engine) validateDocument(ctx context.Context, body string) (Document, error) {
@@ -239,24 +229,27 @@ type workflowFinder interface {
func newRun(ctx context.Context, finder workflowFinder, req StartRequest) (store.NewRun, error) {
w, err := finder.Workflow(ctx, req.OrgID, req.Workflow, 0)
if errors.Is(err, store.ErrNoWorkflow) {
return store.NewRun{}, fmt.Errorf("no workflow named %q", req.Workflow)
return store.NewRun{}, fmt.Errorf("no workflow named %q: %w", req.Workflow, ErrNoWorkflow)
}
if err != nil {
return store.NewRun{}, err
}
if w.Disabled {
return store.NewRun{}, fmt.Errorf("workflow %q: %w", req.Workflow, ErrDisabled)
}
doc, err := ParseDocument(w.Body)
if err != nil {
return store.NewRun{}, fmt.Errorf("workflow %q version %d: %w", req.Workflow, w.Version, err)
}
if err := doc.unsupported(); err != nil {
return store.NewRun{}, err
return store.NewRun{}, refusal{err}
}
input := req.Input
if len(input) == 0 {
input = jsontext.Value("null")
}
if err := doc.checkInputs(decodeInputs(input)); err != nil {
return store.NewRun{}, fmt.Errorf("workflow %q: %w", req.Workflow, err)
return store.NewRun{}, refusal{fmt.Errorf("workflow %q: %w", req.Workflow, err)}
}
return store.NewRun{
OrgID: req.OrgID, Workflow: req.Workflow, Version: w.Version, StartKey: req.Key, Input: input,
@@ -317,7 +310,7 @@ var ErrNotRetryable = errors.New("run can't be retried from there")
// is the step that parked the run. The steps before it keep their results.
func (e *Engine) Retry(ctx context.Context, orgID string, id uuid.UUID, from string) error {
err := e.db.Retry(ctx, orgID, id, from)
if errors.Is(err, store.ErrNotParked) || errors.Is(err, store.ErrNoStep) {
if errors.Is(err, store.ErrNotEnded) || errors.Is(err, store.ErrNoStep) {
return fmt.Errorf("%w: %w", ErrNotRetryable, err)
}
return err
+3 -1
View File
@@ -34,6 +34,8 @@ type fakeWork struct {
// bodies are the stored workflows by name. A workflow not listed is a
// single notify step.
bodies map[string]string
// disabled names the workflows nothing may start.
disabled map[string]bool
// started is every run started for another, once per start key.
started []store.NewRun
}
@@ -96,7 +98,7 @@ func (f *fakeWork) Workflow(_ context.Context, _, name string, _ int) (store.Wor
if !ok {
body = "steps:\n - type: run.notify\n"
}
return store.Workflow{Name: name, Version: 1, Body: body}, nil
return store.Workflow{Name: name, Version: 1, Body: body, Disabled: f.disabled[name]}, nil
}
// StartFor starts a run once per start key, as the store does.
+157
View File
@@ -0,0 +1,157 @@
package runs
import (
json "encoding/json/v2"
"slices"
"strings"
"time"
"github.com/samcharles93/archie-core/modules/runs/internal/store"
)
// The states a step of a run is in.
const (
StagePending = "pending"
StageRunning = "running"
StageWaiting = "waiting"
StageSucceeded = "succeeded"
StageFailed = "failed"
StageSkipped = "skipped"
StageCancelled = "cancelled"
)
// Stage is how far one top-level step of a run's document has got.
type Stage struct {
// Name is the step's id, or its type and position when it has none, as the
// trail names it.
Name string `json:"name"`
Type string `json:"type"`
State string `json:"state"`
StartedAt *time.Time `json:"started_at,omitzero"`
EndedAt *time.Time `json:"ended_at,omitzero"`
Error string `json:"error,omitzero"`
}
// region is the span of recorded steps one top-level step made, which begins at
// the position its marker records.
type region struct {
name string
first int
at time.Time
}
// regions reads the markers a run left where each top-level step began, in the
// order the steps began.
func regions(steps []store.Recorded) []region {
var out []region
for _, s := range steps {
name, ok := strings.CutPrefix(s.Name, enteredPrefix)
if !ok || s.Seq < markerBase {
continue
}
var first int
if json.Unmarshal(s.Output, &first) != nil {
continue
}
out = append(out, region{name: name, first: first, at: s.RecordedAt})
}
return out
}
// stageOf is the region step seq falls in: the last one that began at or before it.
func stageOf(regs []region, seq int) string {
name := ""
for _, r := range regs {
if r.first <= seq {
name = r.name
}
}
return name
}
// stagesOf reads how far each top-level step of doc got in a run from what the
// run recorded. A step the run never reached is pending while the run goes on
// and skipped once it has ended.
func stagesOf(doc Document, steps []store.Recorded, run RunView) []Stage {
regs := regions(steps)
skipped := map[string]bool{}
for _, s := range steps {
if name, ok := strings.CutPrefix(s.Name, "skip:"); ok && s.Seq < markerBase {
skipped[name] = true
}
}
out := make([]Stage, 0, len(doc.Steps))
for i, step := range doc.Steps {
name := step.name(i)
st := Stage{Name: name, Type: stepKind(step), State: StagePending}
if terminal(run.State) {
st.State = StageSkipped
}
if at := slices.IndexFunc(regs, func(r region) bool { return r.name == name }); at >= 0 {
reached(&st, regs, at, skipped[name], run)
}
out = append(out, st)
}
return out
}
// reached fills in a stage for the step that began at regs[at].
func reached(st *Stage, regs []region, at int, skipped bool, run RunView) {
started := regs[at].at
st.StartedAt = &started
last := at == len(regs)-1
switch {
case skipped:
st.State = StageSkipped
case !last:
st.State = StageSucceeded
default:
st.State, st.Error = lastStage(st.Name, run)
}
switch {
case !last:
next := regs[at+1].at
st.EndedAt = &next
case run.FinishedAt != nil && st.State != StageRunning && st.State != StageWaiting:
st.EndedAt = run.FinishedAt
}
}
// lastStage is the state of the step a run reached last, which the run's own
// state decides.
func lastStage(name string, run RunView) (state, failure string) {
switch run.State {
case store.StateQueued, store.StateRunning:
return StageRunning, ""
case store.StateWaiting, store.StateWaitingApproval:
return StageWaiting, ""
case store.StateCancelled:
return StageCancelled, ""
case store.StateFailed:
return StageFailed, run.Error
case store.StateParked:
if reason, ok := strings.CutPrefix(run.Detail, "step "+name+": "); ok {
return StageFailed, reason
}
}
return StageSucceeded, ""
}
func terminal(state string) bool {
switch state {
case store.StateQueued, store.StateRunning, store.StateWaiting, store.StateWaitingApproval:
return false
}
return true
}
// stepKind is the type of a step, or the kind of branching it makes.
func stepKind(s Step) string {
switch {
case s.Switch != nil:
return "switch"
case s.Parallel != nil:
return "parallel"
}
return s.Type
}
+38 -6
View File
@@ -53,6 +53,8 @@ type RunView struct {
CreatedAt time.Time `json:"created_at"`
FinishedAt *time.Time `json:"finished_at,omitzero"`
Result jsontext.Value `json:"result,omitzero"`
// Dry marks a test run of a draft, which changes nothing.
Dry bool `json:"dry,omitzero"`
}
// Trail is a run's decision trail: what started it and every step it took,
@@ -60,6 +62,12 @@ type RunView struct {
type Trail struct {
Run RunView `json:"run"`
Origin *Origin `json:"origin,omitzero"`
// Definition is the workflow document the run executes: the version it
// started under, or for a test run the draft it tested. It is empty when
// the workflow has since been deleted.
Definition string `json:"definition,omitzero"`
// Stages is how far each top-level step of the definition got.
Stages []Stage `json:"stages"`
// Actions are the run's concrete actions in the order they were judged,
// each with its verdicts, the approval it was put to and what came of it.
Actions []ActionTrail `json:"actions"`
@@ -99,7 +107,9 @@ type Effect struct {
// agent's model call, "tool" for its tool call, and "step" for any other
// workflow step.
type TrailEntry struct {
Seq int `json:"seq"`
Seq int `json:"seq"`
// Step is the top-level step of the definition that made the entry.
Step string `json:"step,omitzero"`
At time.Time `json:"at"`
Kind string `json:"kind"`
Name string `json:"name,omitzero"`
@@ -150,7 +160,7 @@ func (e *Engine) Register(api huma.API, orgID string, origins Origins, decisions
}, a.trail)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRun, governance.KindRun), huma.Operation{
OperationID: "retry-run", Method: http.MethodPost, Path: "/api/runs/{id}/retry",
Summary: "Retry a parked run from a step, keeping the results of the steps before it", Tags: tags,
Summary: "Restart a parked or ended run from a step, keeping the results of the steps before it", Tags: tags,
}, a.retry)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindRun), huma.Operation{
OperationID: "cancel-run", Method: http.MethodPost, Path: "/api/runs/{id}/cancel",
@@ -175,7 +185,7 @@ func (a *runAPI) retry(ctx context.Context, in *retryRunInput) (*httpapi.Reply[R
case errors.Is(err, store.ErrNoRun):
return nil, huma.NewError(http.StatusNotFound, "no such run")
case errors.Is(err, ErrNotRetryable):
return nil, huma.NewError(http.StatusConflict, "only a parked run retries, and only from a step it reached")
return nil, huma.NewError(http.StatusConflict, "only a run that has ended or parked retries, and only from a step it reached")
case err != nil:
return nil, huma.NewError(http.StatusInternalServerError, "couldn't retry the run")
}
@@ -255,14 +265,25 @@ func (a *runAPI) trail(ctx context.Context, in *runInput) (*httpapi.Reply[Trail]
if err != nil {
return nil, huma.NewError(http.StatusInternalServerError, "couldn't read the run's steps")
}
t := Trail{Run: view(d.Summary, d.Result), Entries: make([]TrailEntry, 0, len(steps))}
t := Trail{Run: view(d.Summary, d.Result), Entries: make([]TrailEntry, 0, len(steps)), Stages: []Stage{}}
if body, ok := a.definition(ctx, d); ok {
t.Definition = body
if doc, err := ParseDocument(body); err == nil {
t.Stages = stagesOf(doc, steps, t.Run)
}
}
regs := regions(steps)
if o, ok, err := a.origins.Origin(ctx, id); err != nil {
return nil, huma.NewError(http.StatusInternalServerError, "couldn't read what started the run")
} else if ok {
t.Origin = &o
}
for _, s := range steps {
t.Entries = append(t.Entries, entry(s))
e := entry(s)
if s.Seq < markerBase {
e.Step = stageOf(regs, s.Seq)
}
t.Entries = append(t.Entries, e)
}
decisions, err := a.decisions.ForRun(ctx, id)
if err != nil {
@@ -276,6 +297,17 @@ func (a *runAPI) trail(ctx context.Context, in *runInput) (*httpapi.Reply[Trail]
return httpapi.OK(t), nil
}
// definition is the document a run executes. A workflow deleted since the run
// has none to show.
func (a *runAPI) definition(ctx context.Context, d store.Detail) (string, bool) {
if d.Dry {
o, err := readOverlay(d.Overlay)
return o.documentOr(), err == nil
}
w, err := a.db.Workflow(ctx, a.orgID, d.Workflow, d.Version)
return w.Body, err == nil
}
// actions joins each decision with its approval and its effect. An approved
// action's effect is its run step, and the judgement made just before it is
// folded into the action rather than listed as one of its own. An action that
@@ -374,7 +406,7 @@ func effectOf(s store.Recorded) *Effect {
func view(s store.Summary, result jsontext.Value) RunView {
v := RunView{
ID: s.ID, Workflow: s.Workflow, Version: s.Version, State: s.State, Attempts: s.Attempts,
Error: s.Error.String, Detail: s.Detail.String, CreatedAt: s.CreatedAt, Result: result,
Error: s.Error.String, Detail: s.Detail.String, CreatedAt: s.CreatedAt, Result: result, Dry: s.Dry,
}
if s.FinishedAt.Valid {
v.FinishedAt = &s.FinishedAt.Time
+291 -12
View File
@@ -2,11 +2,14 @@ package runs
import (
"context"
"encoding/json/jsontext"
json "encoding/json/v2"
"errors"
"net/http"
"time"
"github.com/danielgtaylor/huma/v2"
"github.com/google/uuid"
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/internal/platform/stableid"
@@ -26,16 +29,70 @@ type WorkflowView struct {
CreatedAt time.Time `json:"created_at"`
// Steps say in plain language what each step does.
Steps []string `json:"steps"`
// Enabled is false for a workflow nothing may start.
Enabled bool `json:"enabled"`
}
func workflowView(w store.Workflow) WorkflowView {
v := WorkflowView{Name: w.Name, Version: w.Version, Body: w.Body, CreatedBy: w.CreatedBy, CreatedAt: w.CreatedAt, Steps: []string{}}
v := WorkflowView{Name: w.Name, Version: w.Version, Body: w.Body, CreatedBy: w.CreatedBy, CreatedAt: w.CreatedAt, Steps: []string{}, Enabled: !w.Disabled}
if doc, err := ParseDocument(w.Body); err == nil {
v.Steps = doc.Describe()
}
return v
}
// DraftView is the unpublished edit of a workflow.
type DraftView struct {
Name string `json:"name"`
Body string `json:"body"`
// BaseVersion is the published version the draft began from, 0 for a
// workflow not yet published.
BaseVersion int `json:"base_version"`
// Revision counts the draft's writes; a write names the one it last saw.
Revision int `json:"revision"`
UpdatedBy string `json:"updated_by"`
UpdatedAt time.Time `json:"updated_at"`
}
func draftView(d store.Draft) DraftView {
return DraftView{Name: d.Name, Body: d.Body, BaseVersion: d.BaseVersion, Revision: d.Revision, UpdatedBy: d.UpdatedBy, UpdatedAt: d.UpdatedAt}
}
// WorkflowStats is what one workflow's runs add up to. Test runs are not
// counted.
type WorkflowStats struct {
Workflow string `json:"workflow"`
Total int `json:"total"`
Succeeded int `json:"succeeded"`
// Failed counts runs that failed, parked or were declined.
Failed int `json:"failed"`
// Active counts runs that haven't ended.
Active int `json:"active"`
// SuccessRate is the share of ended runs that succeeded; absent until one
// has ended.
SuccessRate *float64 `json:"success_rate,omitzero"`
LastRun LastRun `json:"last_run"`
}
// LastRun is a workflow's most recent run.
type LastRun struct {
ID string `json:"id"`
State string `json:"state"`
At time.Time `json:"at"`
}
func workflowStats(s store.Stats) WorkflowStats {
out := WorkflowStats{
Workflow: s.Workflow, Total: s.Total, Succeeded: s.Succeeded, Failed: s.Failed, Active: s.Active,
LastRun: LastRun{ID: s.LastRunID, State: s.LastState, At: s.LastRunAt},
}
if ended := s.Succeeded + s.Failed; ended > 0 {
rate := float64(s.Succeeded) / float64(ended)
out.SuccessRate = &rate
}
return out
}
type workflowAPI struct {
e *Engine
orgID string
@@ -54,21 +111,61 @@ func (e *Engine) registerWorkflows(api huma.API, orgID string) {
}, a.get)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindWorkflow), huma.Operation{
OperationID: "put-workflow", Method: http.MethodPut, Path: "/api/workflows/{name}",
Summary: "Save a workflow document as its next version", Tags: tags,
Summary: "Publish a workflow document as its next version", Tags: tags,
}, a.put)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionDelete, governance.KindWorkflow), huma.Operation{
OperationID: "delete-workflow", Method: http.MethodDelete, Path: "/api/workflows/{name}",
Summary: "Delete a workflow, unless a trigger or another workflow still names it", Tags: tags,
}, a.remove)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindWorkflow), huma.Operation{
OperationID: "set-workflow-enabled", Method: http.MethodPut, Path: "/api/workflows/{name}/enabled",
Summary: "Enable or disable a workflow", Tags: tags,
}, a.setEnabled)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRun, governance.KindWorkflow), huma.Operation{
OperationID: "run-workflow", Method: http.MethodPost, Path: "/api/workflows/{name}/runs",
Summary: "Run a workflow now with an input", Tags: tags, DefaultStatus: http.StatusAccepted,
}, a.run)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindWorkflow), huma.Operation{
OperationID: "list-workflow-drafts", Method: http.MethodGet, Path: "/api/workflow-drafts",
Summary: "List every workflow's unpublished draft", Tags: tags,
}, a.drafts)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindWorkflow), huma.Operation{
OperationID: "get-workflow-draft", Method: http.MethodGet, Path: "/api/workflows/{name}/draft",
Summary: "Get a workflow's unpublished draft", Tags: tags,
}, a.draft)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindWorkflow), huma.Operation{
OperationID: "put-workflow-draft", Method: http.MethodPut, Path: "/api/workflows/{name}/draft",
Summary: "Save a workflow's draft, which no run uses until it is published", Tags: tags,
}, a.putDraft)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindWorkflow), huma.Operation{
OperationID: "discard-workflow-draft", Method: http.MethodDelete, Path: "/api/workflows/{name}/draft",
Summary: "Discard a workflow's draft", Tags: tags, DefaultStatus: http.StatusNoContent,
}, a.discardDraft)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRun, governance.KindWorkflow), huma.Operation{
OperationID: "test-workflow-draft", Method: http.MethodPost, Path: "/api/workflows/{name}/draft/test-run",
Summary: "Test-run a workflow's draft: every action is judged and none that changes something runs", Tags: tags, DefaultStatus: http.StatusAccepted,
}, a.testDraft)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindWorkflow), huma.Operation{
OperationID: "list-workflow-stats", Method: http.MethodGet, Path: "/api/workflow-stats",
Summary: "Count each workflow's runs, with its last run and success rate", Tags: tags,
}, a.stats)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindWorkflow), huma.Operation{
OperationID: "list-workflow-step-types", Method: http.MethodGet, Path: "/api/workflow-step-types",
Summary: "List the step types a workflow document may name, with their settings schemas", Tags: tags,
Summary: "List the step types a workflow document may name, with their titles and settings schemas", Tags: tags,
}, a.stepTypes)
}
type emptyInput struct{}
func (a *workflowAPI) fail(ctx context.Context, what string, err error) error {
a.e.log.ErrorContext(ctx, what, "error", err)
return huma.Error500InternalServerError("couldn't " + what)
}
func (a *workflowAPI) list(ctx context.Context, _ *emptyInput) (*httpapi.Reply[[]WorkflowView], error) {
stored, err := a.e.db.Workflows(ctx, a.orgID)
if err != nil {
a.e.log.ErrorContext(ctx, "list workflows", "error", err)
return nil, huma.Error500InternalServerError("couldn't list the workflows")
return nil, a.fail(ctx, "list the workflows", err)
}
out := make([]WorkflowView, 0, len(stored))
for _, w := range stored {
@@ -88,8 +185,7 @@ func (a *workflowAPI) get(ctx context.Context, in *workflowInput) (*httpapi.Repl
case errors.Is(err, store.ErrNoWorkflow):
return nil, huma.Error404NotFound("no such workflow")
case err != nil:
a.e.log.ErrorContext(ctx, "read workflow", "workflow", in.Name, "error", err)
return nil, huma.Error500InternalServerError("couldn't read the workflow")
return nil, a.fail(ctx, "read the workflow", err)
}
return httpapi.OK(workflowView(w)), nil
}
@@ -98,6 +194,9 @@ type putWorkflowInput struct {
Name string `path:"name" doc:"Lowercase letters and digits, joined by dots or hyphens"`
Body struct {
Body string `json:"body" doc:"The workflow document, as YAML"`
// ExpectedVersion makes the save refuse unless the latest version is
// this one, so an editor can't publish over a version it never saw.
ExpectedVersion *int `json:"expected_version,omitempty" minimum:"0" doc:"The latest version the document was edited from, 0 for a new workflow; the save is refused with 409 when another is stored"`
}
}
@@ -105,22 +204,194 @@ func (a *workflowAPI) put(ctx context.Context, in *putWorkflowInput) (*httpapi.R
if !stableid.Valid(in.Name) {
return nil, huma.Error400BadRequest("a workflow name is lowercase letters and digits, joined by dots or hyphens")
}
version, err := a.e.Install(ctx, a.orgID, in.Name, in.Body.Body, bootstrapAdmin)
version, err := a.e.Publish(ctx, a.orgID, in.Name, in.Body.Body, bootstrapAdmin, in.Body.ExpectedVersion)
if err != nil {
if errors.Is(err, ErrVersionConflict) {
return nil, huma.Error409Conflict("the workflow has another version than the one this was edited from; reload it before publishing")
}
if invalid, ok := errors.AsType[*InvalidError](err); ok {
return nil, Problems(invalid)
}
a.e.log.ErrorContext(ctx, "save workflow", "workflow", in.Name, "error", err)
return nil, huma.Error500InternalServerError("couldn't save the workflow")
return nil, a.fail(ctx, "save the workflow", err)
}
w, err := a.e.db.Workflow(ctx, a.orgID, in.Name, version)
if err != nil {
a.e.log.ErrorContext(ctx, "read workflow", "workflow", in.Name, "error", err)
return nil, huma.Error500InternalServerError("couldn't read the workflow")
return nil, a.fail(ctx, "read the workflow", err)
}
return httpapi.OK(workflowView(w)), nil
}
type nameInput struct {
Name string `path:"name"`
}
func (a *workflowAPI) remove(ctx context.Context, in *nameInput) (*struct{}, error) {
switch err := a.e.Delete(ctx, a.orgID, in.Name); {
case errors.Is(err, store.ErrNoWorkflow):
return nil, huma.Error404NotFound("no such workflow")
case err != nil:
if refs, ok := errors.AsType[*ReferencedError](err); ok {
return nil, huma.Error409Conflict(refs.Error())
}
return nil, a.fail(ctx, "delete the workflow", err)
}
return &struct{}{}, nil
}
type setEnabledInput struct {
Name string `path:"name"`
Body struct {
Enabled bool `json:"enabled"`
}
}
func (a *workflowAPI) setEnabled(ctx context.Context, in *setEnabledInput) (*httpapi.Reply[WorkflowView], error) {
switch err := a.e.SetEnabled(ctx, a.orgID, in.Name, in.Body.Enabled); {
case errors.Is(err, store.ErrNoWorkflow):
return nil, huma.Error404NotFound("no such workflow")
case err != nil:
return nil, a.fail(ctx, "change whether the workflow is enabled", err)
}
return a.get(ctx, &workflowInput{Name: in.Name})
}
type runWorkflowInput struct {
Name string `path:"name"`
Body struct {
Input map[string]any `json:"input,omitempty" doc:"The workflow's inputs by name"`
}
}
func (a *workflowAPI) run(ctx context.Context, in *runWorkflowInput) (*httpapi.Reply[RunView], error) {
input, err := inputOf(in.Body.Input)
if err != nil {
return nil, huma.Error400BadRequest("the input isn't valid JSON")
}
id, err := a.e.Start(ctx, StartRequest{OrgID: a.orgID, Workflow: in.Name, Input: input})
if err != nil {
return nil, a.startError(ctx, err)
}
return a.started(ctx, id)
}
func (a *workflowAPI) started(ctx context.Context, id uuid.UUID) (*httpapi.Reply[RunView], error) {
v, ok, err := a.e.Run(ctx, a.orgID, id)
if err != nil || !ok {
return nil, a.fail(ctx, "read the run", errors.Join(err, errors.New("the started run is missing")))
}
return httpapi.OK(v), nil
}
// startError turns why a run didn't start into the response that says what to
// do about it.
func (a *workflowAPI) startError(ctx context.Context, err error) error {
if invalid, ok := errors.AsType[*InvalidError](err); ok {
return Problems(invalid)
}
switch {
case errors.Is(err, governance.ErrDenied):
return huma.Error403Forbidden(err.Error())
case errors.Is(err, governance.ErrChainUnavailable):
return huma.Error503ServiceUnavailable("the access policies can't decide right now; try again")
case errors.Is(err, ErrNoWorkflow):
return huma.Error404NotFound("no such workflow")
case errors.Is(err, ErrDisabled):
return huma.Error409Conflict(err.Error())
case IsRefusal(err):
return huma.Error400BadRequest(err.Error())
}
return a.fail(ctx, "start the run", err)
}
func (a *workflowAPI) drafts(ctx context.Context, _ *emptyInput) (*httpapi.Reply[[]DraftView], error) {
stored, err := a.e.db.Drafts(ctx, a.orgID)
if err != nil {
return nil, a.fail(ctx, "list the drafts", err)
}
out := make([]DraftView, 0, len(stored))
for _, d := range stored {
out = append(out, draftView(d))
}
return httpapi.OK(out), nil
}
func (a *workflowAPI) draft(ctx context.Context, in *nameInput) (*httpapi.Reply[DraftView], error) {
d, err := a.e.db.Draft(ctx, a.orgID, in.Name)
switch {
case errors.Is(err, store.ErrNoDraft):
return nil, huma.Error404NotFound("the workflow has no draft")
case err != nil:
return nil, a.fail(ctx, "read the draft", err)
}
return httpapi.OK(draftView(d)), nil
}
type putDraftInput struct {
Name string `path:"name" doc:"Lowercase letters and digits, joined by dots or hyphens"`
Body struct {
Body string `json:"body" doc:"The draft document, as YAML. It may be unfinished or invalid; publishing checks it."`
// Revision is the draft's revision as last read, so a write can't
// replace an edit it never saw.
Revision int `json:"revision" minimum:"0" doc:"The revision of the draft as last read, 0 when there is none; the write is refused with 409 when the stored draft is at another"`
}
}
func (a *workflowAPI) putDraft(ctx context.Context, in *putDraftInput) (*httpapi.Reply[DraftView], error) {
if !stableid.Valid(in.Name) {
return nil, huma.Error400BadRequest("a workflow name is lowercase letters and digits, joined by dots or hyphens")
}
d, err := a.e.db.PutDraft(ctx, a.orgID, in.Name, in.Body.Body, bootstrapAdmin, in.Body.Revision)
switch {
case errors.Is(err, store.ErrDraftConflict):
return nil, huma.Error409Conflict("the draft was changed elsewhere; load it before saving")
case err != nil:
return nil, a.fail(ctx, "save the draft", err)
}
return httpapi.OK(draftView(d)), nil
}
func (a *workflowAPI) discardDraft(ctx context.Context, in *nameInput) (*struct{}, error) {
had, err := a.e.db.DeleteDraft(ctx, a.orgID, in.Name)
switch {
case err != nil:
return nil, a.fail(ctx, "discard the draft", err)
case !had:
return nil, huma.Error404NotFound("the workflow has no draft")
}
return &struct{}{}, nil
}
func (a *workflowAPI) testDraft(ctx context.Context, in *runWorkflowInput) (*httpapi.Reply[RunView], error) {
d, err := a.e.db.Draft(ctx, a.orgID, in.Name)
switch {
case errors.Is(err, store.ErrNoDraft):
return nil, huma.Error404NotFound("the workflow has no draft to test")
case err != nil:
return nil, a.fail(ctx, "read the draft", err)
}
input, err := inputOf(in.Body.Input)
if err != nil {
return nil, huma.Error400BadRequest("the input isn't valid JSON")
}
id, err := a.e.StartDry(ctx, DryRequest{OrgID: a.orgID, Workflow: in.Name, Document: d.Body, Input: input})
if err != nil {
return nil, a.startError(ctx, err)
}
return a.started(ctx, id)
}
func (a *workflowAPI) stats(ctx context.Context, _ *emptyInput) (*httpapi.Reply[[]WorkflowStats], error) {
counted, err := a.e.db.Stats(ctx, a.orgID)
if err != nil {
return nil, a.fail(ctx, "count the workflows' runs", err)
}
out := make([]WorkflowStats, 0, len(counted))
for _, s := range counted {
out = append(out, workflowStats(s))
}
return httpapi.OK(out), nil
}
func (a *workflowAPI) stepTypes(context.Context, *emptyInput) (*httpapi.Reply[[]StepType], error) {
return httpapi.OK(StepTypes()), nil
}
@@ -134,3 +405,11 @@ func Problems(invalid *InvalidError) error {
}
return huma.Error400BadRequest(invalid.Error(), details...)
}
// inputOf encodes a run's input, which is null when there is none.
func inputOf(input map[string]any) (jsontext.Value, error) {
if input == nil {
return nil, nil
}
return json.Marshal(input)
}