// 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" "io" "log/slog" "net/http" "regexp" "slices" "strings" "time" "github.com/google/uuid" "github.com/jmoiron/sqlx" "github.com/samcharles93/archie-core/internal/platform/httpjson" "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} } // Routes adds the draft API behind guard. func (m *Module) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handler) { mux.Handle("GET /api/drafts", guard(http.HandlerFunc(m.list))) mux.Handle("POST /api/groups/{id}/draft", guard(http.HandlerFunc(m.create))) mux.Handle("GET /api/drafts/{id}", guard(http.HandlerFunc(m.get))) mux.Handle("PUT /api/drafts/{id}", guard(http.HandlerFunc(m.edit))) mux.Handle("POST /api/drafts/{id}/dry-run", guard(http.HandlerFunc(m.dryRun))) mux.Handle("POST /api/drafts/{id}/publish", guard(http.HandlerFunc(m.publish))) } // 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(w http.ResponseWriter, r *http.Request) { rows, err := m.store.List(r.Context(), m.orgID) if err != nil { m.fail(w, r, "list drafts", err) return } out := make([]View, 0, len(rows)) for _, d := range rows { v, err := m.view(r.Context(), d) if err != nil { m.fail(w, r, "read draft", err) return } out = append(out, v) } httpjson.Write(w, http.StatusOK, out) } // 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(w http.ResponseWriter, r *http.Request) { id, ok := pathID(w, r) if !ok { return } g, found, err := m.groups.Group(r.Context(), id) switch { case err != nil: m.fail(w, r, "read group", err) return case !found: httpjson.Error(w, http.StatusNotFound, "no such group") return } filter, err := json.Marshal(g.Filter) if err != nil { m.fail(w, r, "encode filter", err) return } d, err := m.store.Create(r.Context(), 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 { m.fail(w, r, "create draft", err) return } m.respond(w, r, d) } func (m *Module) get(w http.ResponseWriter, r *http.Request) { d, ok := m.draft(w, r) if !ok { return } m.respond(w, r, d) } type editRequest struct { Name string `json:"name"` Workflow string `json:"workflow"` PolicyKind string `json:"policy_kind"` Policy string `json:"policy"` } // edit replaces a draft's name, workflow and policy after checking them. What // doesn't validate changes nothing. func (m *Module) edit(w http.ResponseWriter, r *http.Request) { d, ok := m.draft(w, r) if !ok { return } if d.PublishedAt.Valid { httpjson.Error(w, http.StatusConflict, "a published draft can't be edited") return } var req editRequest if err := httpjson.Read(r, &req); err != nil { httpjson.Error(w, http.StatusBadRequest, err.Error()) return } if err := m.check(r.Context(), req.Name, req.Workflow, req.PolicyKind, req.Policy); err != nil { writeInvalid(w, err) return } switch err := m.store.Edit(r.Context(), m.orgID, d.ID, req.Name, req.Workflow, req.PolicyKind, req.Policy); { case errors.Is(err, store.ErrTaken): httpjson.Error(w, http.StatusConflict, "another draft has that name") return case err != nil: m.fail(w, r, "edit draft", err) return } d, err := m.store.ByID(r.Context(), m.orgID, d.ID) if err != nil { m.fail(w, r, "read draft", err) return } m.respond(w, r, 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 writeInvalid(w http.ResponseWriter, err error) { var invalid *runs.InvalidError switch { case errors.As(err, &invalid): httpjson.Write(w, http.StatusBadRequest, map[string]any{"error": invalid.Error(), "problems": invalid.Problems}) case errors.Is(err, judgement.ErrInvalidPolicy): httpjson.Write(w, http.StatusBadRequest, map[string]any{ "error": err.Error(), "problems": []runs.Problem{{Path: "policy", Message: err.Error()}}, }) default: httpjson.Error(w, http.StatusInternalServerError, "couldn't check the draft") } } type dryRunRequest struct { EventID uuid.UUID `json:"event_id"` } // 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(w http.ResponseWriter, r *http.Request) { d, ok := m.draft(w, r) if !ok { return } var req dryRunRequest if err := httpjson.Read(r, &req); err != nil && !errors.Is(err, io.EOF) { httpjson.Error(w, http.StatusBadRequest, err.Error()) return } if err := m.check(r.Context(), d.Name, d.Document, d.PolicyKind, d.Policy); err != nil { writeInvalid(w, err) return } stored, err := m.groups.GroupEvents(r.Context(), d.GroupID, replayable) if err != nil { m.fail(w, r, "read the group's events", err) return } event, found := pick(stored, req.EventID) if !found { httpjson.Error(w, http.StatusConflict, "the group has no stored event to replay") return } runID, err := m.workflows.StartDry(r.Context(), runs.DryRequest{ OrgID: m.orgID, Workflow: d.Name, Document: d.Document, PolicyKind: d.PolicyKind, Policy: d.Policy, Input: event.Input, }) if err != nil { m.fail(w, r, "start the dry run", err) return } if err := m.groups.Replayed(r.Context(), event.ID, d.Name, runID); err != nil { m.fail(w, r, "record the replay", err) return } if err := m.store.SetDryRun(r.Context(), m.orgID, d.ID, runID, event.ID); err != nil { m.fail(w, r, "record the dry run", err) return } d, err = m.store.ByID(r.Context(), m.orgID, d.ID) if err != nil { m.fail(w, r, "read draft", err) return } m.respond(w, r, 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(w http.ResponseWriter, r *http.Request) { d, ok := m.draft(w, r) if !ok { return } ctx := r.Context() if err := m.check(ctx, d.Name, d.Document, d.PolicyKind, d.Policy); err != nil { writeInvalid(w, err) return } if !d.InstalledVersion.Valid { taken, err := m.workflows.Has(ctx, m.orgID, d.Name) if err != nil { m.fail(w, r, "check the workflow name", err) return } if taken { httpjson.Error(w, http.StatusConflict, "a workflow named "+d.Name+" already exists; rename the draft") return } } by := "draft:" + d.Name if strings.TrimSpace(d.Policy) != "" { if _, err := m.policies.Append(ctx, d.PolicyKind, d.Policy, by); err != nil { m.fail(w, r, "add the policy", err) return } } version, err := m.workflows.Install(ctx, m.orgID, d.Name, d.Document, by) if err != nil { m.fail(w, r, "install the workflow", err) return } if err := m.store.MarkInstalled(ctx, m.orgID, d.ID, version); err != nil { m.fail(w, r, "record the workflow version", err) return } var filter map[string]string if err := json.Unmarshal(d.Filter, &filter); err != nil { m.fail(w, r, "read the trigger filter", err) return } if err := m.groups.SaveTrigger(ctx, events.TriggerSpec{ Name: d.Name, Source: d.Source, EventType: d.EventType, Filter: filter, Workflow: d.Name, }); err != nil { m.fail(w, r, "save the trigger", err) return } if err := m.store.MarkPublished(ctx, m.orgID, d.ID); err != nil { m.fail(w, r, "mark the draft published", err) return } d, err = m.store.ByID(ctx, m.orgID, d.ID) if err != nil { m.fail(w, r, "read draft", err) return } m.respond(w, r, d) } func (m *Module) draft(w http.ResponseWriter, r *http.Request) (store.Draft, bool) { id, ok := pathID(w, r) if !ok { return store.Draft{}, false } d, err := m.store.ByID(r.Context(), m.orgID, id) switch { case errors.Is(err, store.ErrNotFound): httpjson.Error(w, http.StatusNotFound, "no such draft") return store.Draft{}, false case err != nil: m.fail(w, r, "read draft", err) return store.Draft{}, false } return d, true } func (m *Module) respond(w http.ResponseWriter, r *http.Request, d store.Draft) { v, err := m.view(r.Context(), d) if err != nil { m.fail(w, r, "read draft", err) return } httpjson.Write(w, http.StatusOK, v) } func (m *Module) fail(w http.ResponseWriter, r *http.Request, what string, err error) { m.log.ErrorContext(r.Context(), what, "error", err) httpjson.Error(w, http.StatusInternalServerError, "couldn't "+what) } func pathID(w http.ResponseWriter, r *http.Request) (uuid.UUID, bool) { id, err := uuid.Parse(r.PathValue("id")) if err != nil { httpjson.Error(w, http.StatusBadRequest, "an id is a UUID") return uuid.Nil, false } return id, true }