// Package drafts holds what an unmatched group of events could become: the // trigger it proposes, the workflow that trigger would start and any policy // that workflow needs, with a plain-language summary and a dry run. Nothing in // a draft is in force until it is published. 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 is how many of a group's newest events a dry run can choose from. const replayable = 50 // Groups is where a draft finds the unmatched events it is made from, and // where its trigger is saved. 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 stores workflow documents and runs them dry. 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 checks a draft's policy against the set in force and adds it. 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 one of the group's events through the draft, changing nothing", 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 a draft as the API returns it. 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 is the last dry run of the draft as it stands. 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"} ) // summarize says in plain language when a draft fires and what it does. It is // built from the draft's own fields, so it can't disagree with them. 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 is a trigger name that is valid and tells groups apart. 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 makes a group's draft, or returns the one it has. A new draft // proposes the group's trigger and a copy of the investigate 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("an id is 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"` } } // edit replaces a draft's name, workflow and policy after checking them. What // doesn't validate changes nothing. 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) } // check validates what a draft would put in force. 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 replays one of the group's stored events through the draft's workflow // in dry mode: the newest by default. 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 returns the event asked for, or the newest when none is. 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 puts a draft in force: its policy is added to the set, its workflow // is installed as the next version, and last its trigger is saved, so nothing // fires before the rules that govern it exist. A retry after a failure carries // on from where it stopped. 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("an id is 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) }