Files
samandCopilot 64dfad6d53 feat(runs): add typed results and model aliases (#2043)
Also fix repository-free message.send validation (#2046) and add a single-binary development smoke path (#1977).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-18 23:47:35 +11:00

460 lines
15 KiB
Go

// Package drafts manages proposed triggers, workflows and policies for groups
// of unmatched events. Drafts can be tested by replaying a stored event in a
// dry run before the trigger is enabled.
package drafts
import (
"context"
"encoding/json/jsontext"
json "encoding/json/v2"
"errors"
"fmt"
"log/slog"
"net/http"
"regexp"
"slices"
"strings"
"time"
"github.com/danielgtaylor/huma/v2"
"github.com/google/uuid"
"github.com/jmoiron/sqlx"
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/modules/drafts/internal/store"
"github.com/samcharles93/archie-core/modules/events"
"github.com/samcharles93/archie-core/modules/judgement"
"github.com/samcharles93/archie-core/modules/runs"
)
// replayable limits dry runs to the group's most recently received events.
const replayable = 50
// Groups provides unmatched event groups, replay tracking and trigger storage.
type Groups interface {
Group(ctx context.Context, id uuid.UUID) (events.Group, bool, error)
GroupEvents(ctx context.Context, id uuid.UUID, limit int) ([]events.Stored, error)
Replayed(ctx context.Context, eventID uuid.UUID, trigger string, runID uuid.UUID) error
SaveTrigger(ctx context.Context, t events.TriggerSpec) error
}
// Workflows installs workflow documents and manages dry runs.
type Workflows interface {
Install(ctx context.Context, orgID, name, body, by string) (int, error)
Has(ctx context.Context, orgID, name string) (bool, error)
StartDry(ctx context.Context, req runs.DryRequest) (uuid.UUID, error)
DryReport(ctx context.Context, orgID string, id uuid.UUID) (runs.DryReport, bool, error)
}
// Policies validates a draft's policy against the current policy set and
// adds it when the draft is published.
type Policies interface {
Check(ctx context.Context, kind, extra string) error
Append(ctx context.Context, kind, extra, by string) (judgement.PolicySetView, error)
}
// Module holds one organisation's drafts.
type Module struct {
orgID string
store *store.Store
groups Groups
workflows Workflows
policies Policies
log *slog.Logger
}
// NewModule returns the drafts module for orgID.
func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, g Groups, w Workflows, p Policies) *Module {
return &Module{orgID: orgID, store: store.New(db), groups: g, workflows: w, policies: p, log: log}
}
// Register adds the draft API.
func (m *Module) Register(api huma.API) {
tags := []string{"Drafts"}
huma.Register(api, huma.Operation{
OperationID: "list-drafts", Method: http.MethodGet, Path: "/api/drafts",
Summary: "List drafts", Tags: tags,
}, m.list)
huma.Register(api, huma.Operation{
OperationID: "draft-group", Method: http.MethodPost, Path: "/api/groups/{id}/draft",
Summary: "Draft a trigger and workflow for a group of unmatched events", Tags: tags,
}, m.create)
huma.Register(api, huma.Operation{
OperationID: "get-draft", Method: http.MethodGet, Path: "/api/drafts/{id}",
Summary: "Get a draft", Tags: tags,
}, m.get)
huma.Register(api, huma.Operation{
OperationID: "edit-draft", Method: http.MethodPut, Path: "/api/drafts/{id}",
Summary: "Change a draft's name, workflow and policy", Tags: tags,
}, m.edit)
huma.Register(api, huma.Operation{
OperationID: "dry-run-draft", Method: http.MethodPost, Path: "/api/drafts/{id}/dry-run",
Summary: "Replay a stored event against the draft workflow and policy in a dry run", Tags: tags,
}, m.dryRun)
huma.Register(api, huma.Operation{
OperationID: "publish-draft", Method: http.MethodPost, Path: "/api/drafts/{id}/publish",
Summary: "Install the draft's workflow, policy and trigger", Tags: tags,
}, m.publish)
}
type idInput struct {
ID string `path:"id" format:"uuid"`
}
// View is the API representation of a draft.
type View struct {
ID uuid.UUID `json:"id"`
GroupID uuid.UUID `json:"group_id"`
Name string `json:"name"`
Trigger Trigger `json:"trigger"`
// Workflow is the workflow document the trigger would start.
Workflow string `json:"workflow"`
PolicyKind string `json:"policy_kind"`
// Policy is Cedar policy text added to the set in force when published.
Policy string `json:"policy"`
Summary string `json:"summary"`
// DryRun reports the latest dry run since the draft was last edited.
DryRun *runs.DryReport `json:"dry_run,omitzero"`
DryEventID *uuid.UUID `json:"dry_event_id,omitzero"`
PublishedAt *time.Time `json:"published_at,omitzero"`
}
// Trigger is the trigger a draft proposes.
type Trigger struct {
Source string `json:"source"`
EventType string `json:"event_type"`
Filter jsontext.Value `json:"filter"`
}
func (m *Module) view(ctx context.Context, d store.Draft) (View, error) {
v := View{
ID: d.ID, GroupID: d.GroupID, Name: d.Name,
Trigger: Trigger{Source: d.Source, EventType: d.EventType, Filter: d.Filter},
Workflow: d.Document, PolicyKind: d.PolicyKind, Policy: d.Policy,
Summary: summarize(d),
}
if d.PublishedAt.Valid {
v.PublishedAt = &d.PublishedAt.Time
}
if d.DryEventID.Valid {
v.DryEventID = &d.DryEventID.UUID
}
if d.DryRunID.Valid {
rep, ok, err := m.workflows.DryReport(ctx, m.orgID, d.DryRunID.UUID)
if err != nil {
return View{}, fmt.Errorf("read dry run: %w", err)
}
if ok {
v.DryRun = &rep
}
}
return v, nil
}
var (
policyID = regexp.MustCompile(`@id\("([^"]+)"\)`)
nameChars = regexp.MustCompile(`[^a-z0-9]+`)
validName = regexp.MustCompile(`^[a-z][a-z0-9-]{0,62}$`)
policyKinds = map[string]string{judgement.KindHardRules: "hard rule", judgement.KindChangeRequest: "change request rule"}
)
func summarize(d store.Draft) string {
var filter map[string]string
_ = json.Unmarshal(d.Filter, &filter)
var b strings.Builder
fmt.Fprintf(&b, "When %s sends %s", d.Source, d.EventType)
if len(filter) > 0 {
pairs := make([]string, 0, len(filter))
for k, v := range filter {
pairs = append(pairs, k+"="+v)
}
slices.Sort(pairs)
b.WriteString(" matching " + strings.Join(pairs, ", "))
}
fmt.Fprintf(&b, ", Archie runs %q.", d.Name)
doc, err := runs.ParseDocument(d.Document)
if err != nil {
b.WriteString(" The workflow is not valid.")
}
for _, line := range doc.Describe() {
b.WriteString(" " + line + ".")
}
if strings.TrimSpace(d.Policy) != "" {
ids := policyID.FindAllStringSubmatch(d.Policy, -1)
names := make([]string, 0, len(ids))
for _, id := range ids {
names = append(names, id[1])
}
fmt.Fprintf(&b, " It adds %s policies", policyKinds[d.PolicyKind])
if len(names) > 0 {
b.WriteString(": " + strings.Join(names, ", "))
}
b.WriteString(".")
}
return b.String()
}
// defaultName uses part of the group ID to distinguish groups with the same
// source and event type.
func defaultName(g events.Group) string {
slug := strings.Trim(nameChars.ReplaceAllString(strings.ToLower(g.Source+"-"+g.EventType), "-"), "-")
if len(slug) > 50 {
slug = strings.Trim(slug[:50], "-")
}
return slug + "-" + g.ID.String()[:6]
}
func (m *Module) list(ctx context.Context, _ *struct{}) (*httpapi.Reply[[]View], error) {
rows, err := m.store.List(ctx, m.orgID)
if err != nil {
return nil, m.fail(ctx, "list drafts", err)
}
out := make([]View, 0, len(rows))
for _, d := range rows {
v, err := m.view(ctx, d)
if err != nil {
return nil, m.fail(ctx, "read draft", err)
}
out = append(out, v)
}
return httpapi.OK(out), nil
}
// create reuses an existing group draft rather than replacing any edits
// with the default investigation workflow.
func (m *Module) create(ctx context.Context, in *idInput) (*httpapi.Reply[View], error) {
id, err := uuid.Parse(in.ID)
if err != nil {
return nil, huma.Error400BadRequest("ID must be a UUID")
}
g, found, err := m.groups.Group(ctx, id)
switch {
case err != nil:
return nil, m.fail(ctx, "read group", err)
case !found:
return nil, huma.Error404NotFound("no such group")
}
filter, err := json.Marshal(g.Filter)
if err != nil {
return nil, m.fail(ctx, "encode filter", err)
}
d, err := m.store.Create(ctx, store.Draft{
ID: uuid.New(), OrgID: m.orgID, GroupID: g.ID, Name: defaultName(g), Source: g.Source, EventType: g.EventType,
Filter: filter, Document: runs.InvestigateDocument(), PolicyKind: judgement.KindHardRules,
})
if err != nil {
return nil, m.fail(ctx, "create draft", err)
}
return m.respond(ctx, d)
}
func (m *Module) get(ctx context.Context, in *idInput) (*httpapi.Reply[View], error) {
d, err := m.draft(ctx, in.ID)
if err != nil {
return nil, err
}
return m.respond(ctx, d)
}
type editInput struct {
ID string `path:"id" format:"uuid"`
Body struct {
Name string `json:"name"`
Workflow string `json:"workflow" doc:"The workflow document"`
PolicyKind string `json:"policy_kind" enum:"hard_rules,change_request"`
Policy string `json:"policy,omitzero" doc:"Cedar policy text added when the draft is published"`
}
}
func (m *Module) edit(ctx context.Context, in *editInput) (*httpapi.Reply[View], error) {
d, err := m.draft(ctx, in.ID)
if err != nil {
return nil, err
}
if d.PublishedAt.Valid {
return nil, huma.Error409Conflict("a published draft can't be edited")
}
req := in.Body
if err := m.check(ctx, req.Name, req.Workflow, req.PolicyKind, req.Policy); err != nil {
return nil, invalid(err)
}
switch err := m.store.Edit(ctx, m.orgID, d.ID, req.Name, req.Workflow, req.PolicyKind, req.Policy); {
case errors.Is(err, store.ErrTaken):
return nil, huma.Error409Conflict("another draft has that name")
case err != nil:
return nil, m.fail(ctx, "edit draft", err)
}
d, err = m.store.ByID(ctx, m.orgID, d.ID)
if err != nil {
return nil, m.fail(ctx, "read draft", err)
}
return m.respond(ctx, d)
}
func (m *Module) check(ctx context.Context, name, document, policyKind, policy string) error {
if !validName.MatchString(name) {
return &runs.InvalidError{Problems: []runs.Problem{{Path: "name", Message: "lowercase letters, digits and hyphens, starting with a letter"}}}
}
if _, err := runs.ParseDocument(document); err != nil {
return err
}
if _, ok := policyKinds[policyKind]; !ok {
return &runs.InvalidError{Problems: []runs.Problem{{Path: "policy_kind", Message: "hard_rules or change_request"}}}
}
if strings.TrimSpace(policy) == "" {
return nil
}
return m.policies.Check(ctx, policyKind, policy)
}
func invalid(err error) error {
var problem *runs.InvalidError
switch {
case errors.As(err, &problem):
return runs.Problems(problem)
case errors.Is(err, judgement.ErrInvalidPolicy):
return huma.Error400BadRequest(err.Error(), &huma.ErrorDetail{Location: "policy", Message: err.Error()})
default:
return huma.Error500InternalServerError("couldn't check the draft")
}
}
type dryRunInput struct {
ID string `path:"id" format:"uuid"`
Body *struct {
EventID uuid.UUID `json:"event_id,omitzero" doc:"The stored event to replay; the newest by default"`
}
}
// dryRun tests the draft workflow and policy against a stored event. If the
// caller omits the event ID, it replays the most recently received event.
func (m *Module) dryRun(ctx context.Context, in *dryRunInput) (*httpapi.Reply[View], error) {
d, err := m.draft(ctx, in.ID)
if err != nil {
return nil, err
}
var eventID uuid.UUID
if in.Body != nil {
eventID = in.Body.EventID
}
if err := m.check(ctx, d.Name, d.Document, d.PolicyKind, d.Policy); err != nil {
return nil, invalid(err)
}
stored, err := m.groups.GroupEvents(ctx, d.GroupID, replayable)
if err != nil {
return nil, m.fail(ctx, "read the group's events", err)
}
event, found := pick(stored, eventID)
if !found {
return nil, huma.Error409Conflict("the group has no stored event to replay")
}
runID, err := m.workflows.StartDry(ctx, runs.DryRequest{
OrgID: m.orgID, Workflow: d.Name, Document: d.Document, PolicyKind: d.PolicyKind, Policy: d.Policy, Input: event.Input,
})
if err != nil {
return nil, m.fail(ctx, "start the dry run", err)
}
if err := m.groups.Replayed(ctx, event.ID, d.Name, runID); err != nil {
return nil, m.fail(ctx, "record the replay", err)
}
if err := m.store.SetDryRun(ctx, m.orgID, d.ID, runID, event.ID); err != nil {
return nil, m.fail(ctx, "record the dry run", err)
}
d, err = m.store.ByID(ctx, m.orgID, d.ID)
if err != nil {
return nil, m.fail(ctx, "read draft", err)
}
return m.respond(ctx, d)
}
// pick expects events in newest-first order so a missing ID selects the newest.
func pick(stored []events.Stored, id uuid.UUID) (events.Stored, bool) {
for _, e := range stored {
if id == uuid.Nil || e.ID == id {
return e, true
}
}
return events.Stored{}, false
}
// publish installs the policy and workflow before saving the trigger so the
// trigger cannot fire before both are available. A recorded workflow version
// lets a retry skip the name-conflict check. The retry still calls the policy
// and workflow installers, which avoid duplicating unchanged content.
func (m *Module) publish(ctx context.Context, in *idInput) (*httpapi.Reply[View], error) {
d, err := m.draft(ctx, in.ID)
if err != nil {
return nil, err
}
if err := m.check(ctx, d.Name, d.Document, d.PolicyKind, d.Policy); err != nil {
return nil, invalid(err)
}
if !d.InstalledVersion.Valid {
taken, err := m.workflows.Has(ctx, m.orgID, d.Name)
if err != nil {
return nil, m.fail(ctx, "check the workflow name", err)
}
if taken {
return nil, huma.Error409Conflict("a workflow named " + d.Name + " already exists; rename the draft")
}
}
by := "draft:" + d.Name
if strings.TrimSpace(d.Policy) != "" {
if _, err := m.policies.Append(ctx, d.PolicyKind, d.Policy, by); err != nil {
return nil, m.fail(ctx, "add the policy", err)
}
}
version, err := m.workflows.Install(ctx, m.orgID, d.Name, d.Document, by)
if err != nil {
return nil, m.fail(ctx, "install the workflow", err)
}
if err := m.store.MarkInstalled(ctx, m.orgID, d.ID, version); err != nil {
return nil, m.fail(ctx, "record the workflow version", err)
}
var filter map[string]string
if err := json.Unmarshal(d.Filter, &filter); err != nil {
return nil, m.fail(ctx, "read the trigger filter", err)
}
if err := m.groups.SaveTrigger(ctx, events.TriggerSpec{
Name: d.Name, Source: d.Source, EventType: d.EventType, Filter: filter, Workflow: d.Name,
}); err != nil {
return nil, m.fail(ctx, "save the trigger", err)
}
if err := m.store.MarkPublished(ctx, m.orgID, d.ID); err != nil {
return nil, m.fail(ctx, "mark the draft published", err)
}
d, err = m.store.ByID(ctx, m.orgID, d.ID)
if err != nil {
return nil, m.fail(ctx, "read draft", err)
}
return m.respond(ctx, d)
}
func (m *Module) draft(ctx context.Context, rawID string) (store.Draft, error) {
id, err := uuid.Parse(rawID)
if err != nil {
return store.Draft{}, huma.Error400BadRequest("ID must be a UUID")
}
d, err := m.store.ByID(ctx, m.orgID, id)
switch {
case errors.Is(err, store.ErrNotFound):
return store.Draft{}, huma.Error404NotFound("no such draft")
case err != nil:
return store.Draft{}, m.fail(ctx, "read draft", err)
}
return d, nil
}
func (m *Module) respond(ctx context.Context, d store.Draft) (*httpapi.Reply[View], error) {
v, err := m.view(ctx, d)
if err != nil {
return nil, m.fail(ctx, "read draft", err)
}
return httpapi.OK(v), nil
}
func (m *Module) fail(ctx context.Context, what string, err error) error {
m.log.ErrorContext(ctx, what, "error", err)
return huma.Error500InternalServerError("couldn't " + what)
}