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.
416 lines
16 KiB
Go
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)
|
|
}
|