Files
archie/modules/runs/workflows_api.go
T
sam ce70d4f3ee feat(runs): workflow documents take today's step shape, references and when (#2039)
A step is id/type/settings with when and on_failure; the five kinds become
the types agent.run (inline mission), connector.action, approval.wait,
run.notify and workflow.sleep. Documents declare inputs, repository,
instructions, identity and profile; references are {{ task|inputs|steps }}
checked at save. Any number of approval steps, each asking only about what
was held since; actions still held at the end are put to people before the
run finishes. Triggers are refused for a workflow they can't start, and the
workflows API lists, reads and saves documents beside a step-type catalog.

Copied from internal/domain/workflow: definition.go, step_refs.go,
step_flow.go's checks, control_steps.go's when parser, vocabulary.go and
task/interface.go. stableid moves to internal/platform.
2026-11-17 18:43:45 +11:00

136 lines
4.7 KiB
Go

package runs
import (
"context"
"errors"
"net/http"
"time"
"github.com/danielgtaylor/huma/v2"
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/internal/platform/stableid"
"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"`
}
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{}}
if doc, err := ParseDocument(w.Body); err == nil {
v.Steps = doc.Describe()
}
return v
}
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"}
huma.Register(api, huma.Operation{
OperationID: "list-workflows", Method: http.MethodGet, Path: "/api/workflows",
Summary: "List every workflow at its latest version", Tags: tags,
}, a.list)
huma.Register(api, huma.Operation{
OperationID: "get-workflow", Method: http.MethodGet, Path: "/api/workflows/{name}",
Summary: "Get a workflow", Tags: tags,
}, a.get)
huma.Register(api, huma.Operation{
OperationID: "put-workflow", Method: http.MethodPut, Path: "/api/workflows/{name}",
Summary: "Save a workflow document as its next version", Tags: tags,
}, a.put)
huma.Register(api, 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,
}, a.stepTypes)
}
type emptyInput struct{}
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")
}
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:
a.e.log.ErrorContext(ctx, "read workflow", "workflow", in.Name, "error", err)
return nil, huma.Error500InternalServerError("couldn't read the workflow")
}
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"`
}
}
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.Install(ctx, a.orgID, in.Name, in.Body.Body, bootstrapAdmin)
if err != nil {
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")
}
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 httpapi.OK(workflowView(w)), 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...)
}