Files
sam 682995bdf7 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.
2026-11-22 11:34:49 +11:00

416 lines
16 KiB
Go

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"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/runs/internal/store"
)
// bootstrapAdmin is who a change made with the admin token is recorded as.
const bootstrapAdmin = "admin"
// WorkflowView is one stored version of a workflow.
type WorkflowView struct {
Name string `json:"name"`
Version int `json:"version"`
Body string `json:"body"`
CreatedBy string `json:"created_by"`
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{}, 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
}
func (e *Engine) registerWorkflows(api huma.API, orgID string) {
a := &workflowAPI{e: e, orgID: orgID}
tags := []string{"Workflows"}
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindWorkflow), huma.Operation{
OperationID: "list-workflows", Method: http.MethodGet, Path: "/api/workflows",
Summary: "List every workflow at its latest version", Tags: tags,
}, a.list)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindWorkflow), huma.Operation{
OperationID: "get-workflow", Method: http.MethodGet, Path: "/api/workflows/{name}",
Summary: "Get a workflow", Tags: tags,
}, a.get)
httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindWorkflow), huma.Operation{
OperationID: "put-workflow", Method: http.MethodPut, Path: "/api/workflows/{name}",
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 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 {
return nil, a.fail(ctx, "list the workflows", err)
}
out := make([]WorkflowView, 0, len(stored))
for _, w := range stored {
out = append(out, workflowView(w))
}
return httpapi.OK(out), nil
}
type workflowInput struct {
Name string `path:"name"`
Version int `query:"version" minimum:"1" doc:"A past version; the latest by default"`
}
func (a *workflowAPI) get(ctx context.Context, in *workflowInput) (*httpapi.Reply[WorkflowView], error) {
w, err := a.e.db.Workflow(ctx, a.orgID, in.Name, in.Version)
switch {
case errors.Is(err, store.ErrNoWorkflow):
return nil, huma.Error404NotFound("no such workflow")
case err != nil:
return nil, a.fail(ctx, "read the workflow", err)
}
return httpapi.OK(workflowView(w)), nil
}
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"`
}
}
func (a *workflowAPI) put(ctx context.Context, in *putWorkflowInput) (*httpapi.Reply[WorkflowView], error) {
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.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)
}
return nil, a.fail(ctx, "save the workflow", err)
}
w, err := a.e.db.Workflow(ctx, a.orgID, in.Name, version)
if err != nil {
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
}
// Problems is a document's problems as a 400 response, one detail per problem
// at its path.
func Problems(invalid *InvalidError) error {
details := make([]error, 0, len(invalid.Problems))
for _, p := range invalid.Problems {
details = append(details, &huma.ErrorDetail{Location: p.Path, Message: p.Message})
}
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)
}