Files
archie/modules/events/api_sources.go
T
sam 61f576a25c feat(events): capture, event types, mappings and trigger approval on the binary (#2062, #2098)
Event types, field mappings and the stored-delivery inspector move into
modules/events: copied from internal/domain/eventtype and
internal/domain/mapping, which the old services still import. Each stored
event records how its delivery was verified; a source that checks nothing
refuses deliveries until approved; triggers gain approve, pause, resume,
event-type and mapping binding, dispatch history and delete. The captures,
mappings and bindings sections are reported as served.
2026-11-22 11:39:46 +11:00

342 lines
14 KiB
Go

package events
import (
"context"
"crypto/rand"
"encoding/hex"
"errors"
"fmt"
"net/http"
"net/textproto"
"strings"
"github.com/danielgtaylor/huma/v2"
"golang.org/x/net/http/httpguts"
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/modules/events/internal/store"
"github.com/samcharles93/archie-core/modules/governance"
)
// registerSourceSettings adds the operations that change one setting of a
// source, and the trigger lifecycle. Approving an unsigned source or a
// trigger has its own grant, so a role that may edit them cannot also approve.
func (m *Module) registerSourceSettings(api huma.API) {
tags := []string{"Events"}
op := func(id, method, path, summary string) huma.Operation {
return huma.Operation{OperationID: id, Method: method, Path: path, Summary: summary, Tags: tags}
}
admin := httpapi.AdminAuthorized[governance.Action, governance.ResourceKind]
httpapi.Register(api, admin(governance.ActionUpdate, governance.KindSource), op("set-source-name", http.MethodPut, "/api/sources/{name}/name", "Label a source"), m.setSourceName)
httpapi.Register(api, admin(governance.ActionUpdate, governance.KindSource), op("set-source-delivery-header", http.MethodPut, "/api/sources/{name}/delivery-header", "Name the header a sender repeats when it retries a delivery"), m.setDeliveryHeader)
httpapi.Register(api, admin(governance.ActionUpdate, governance.KindSource), op("set-source-capture", http.MethodPut, "/api/sources/{name}/capture", "Keep or stop keeping the headers and payloads a source receives"), m.setCapture)
httpapi.Register(api, admin(governance.ActionUpdate, governance.KindSource), op("set-source-signing", http.MethodPost, "/api/sources/{name}/signing", "Require an HMAC signature, or ask to take unsigned deliveries"), m.setSigning)
httpapi.Register(api, admin(governance.ActionApprove, governance.KindSource), op("approve-source-unsigned", http.MethodPost, "/api/sources/{name}/approve-unsigned", "Accept deliveries that carry no signature"), m.approveUnsigned)
httpapi.Register(api, admin(governance.ActionReadSecret, governance.KindSecret), op("rotate-source-secret", http.MethodPost, "/api/sources/{name}/secret", "Replace a signed source's secret and return it once"), m.rotateSecret)
httpapi.Register(api, admin(governance.ActionDelete, governance.KindSource), op("delete-source", http.MethodDelete, "/api/sources/{name}", "Delete a source"), m.deleteSource)
httpapi.Register(api, admin(governance.ActionApprove, governance.KindTrigger), op("approve-trigger", http.MethodPost, "/api/triggers/{name}/approve", "Arm a trigger that waits for approval"), m.approveTrigger)
httpapi.Register(api, admin(governance.ActionUpdate, governance.KindTrigger), op("pause-trigger", http.MethodPost, "/api/triggers/{name}/pause", "Stop a trigger firing"), m.pauseTrigger)
httpapi.Register(api, admin(governance.ActionUpdate, governance.KindTrigger), op("resume-trigger", http.MethodPost, "/api/triggers/{name}/resume", "Return a paused trigger to waiting for approval"), m.resumeTrigger)
httpapi.Register(api, admin(governance.ActionDelete, governance.KindTrigger), op("delete-trigger", http.MethodDelete, "/api/triggers/{name}", "Delete a trigger"), m.deleteTrigger)
httpapi.Register(api, admin(governance.ActionRead, governance.KindTrigger), op("list-trigger-dispatches", http.MethodGet, "/api/triggers/{name}/dispatches", "List the runs a trigger started"), m.triggerDispatches)
}
type sourceInput struct {
Name string `path:"name"`
}
// Signing states a source reports: an HMAC signature, a bearer token, or no
// verification, which waits for approval before it takes deliveries.
const (
signingSigned = "signed"
signingToken = "token"
signingPending = "unsigned_pending_approval"
signingUnsigned = "unsigned"
)
func signingOf(src store.Source) string {
switch {
case src.Verification == store.HMAC:
return signingSigned
case src.Verification == store.Token:
return signingToken
case src.UnsignedApproved:
return signingUnsigned
}
return signingPending
}
// readSource loads a source for a settings change.
func (m *Module) readSource(ctx context.Context, name string) (store.Source, error) {
src, err := m.store.Source(ctx, m.orgID, name)
if errors.Is(err, store.ErrNotFound) {
return src, huma.Error404NotFound("no such source")
}
if err != nil {
return src, huma.Error500InternalServerError("couldn't read the source", err)
}
return src, nil
}
// sourceReply reads a source back after a change. secret is a signing secret
// issued by the change, returned once.
func (m *Module) sourceReply(ctx context.Context, name, secret string) (*httpapi.Reply[sourceView], error) {
src, err := m.readSource(ctx, name)
if err != nil {
return nil, err
}
view, err := viewOfSource(src)
if err != nil {
return nil, huma.Error500InternalServerError("couldn't read the key fields of "+name, err)
}
view.Secret = secret
return httpapi.OK(view), nil
}
type sourceNameInput struct {
Name string `path:"name"`
Body struct {
Name string `json:"name" maxLength:"100"`
}
}
func (m *Module) setSourceName(ctx context.Context, in *sourceNameInput) (*httpapi.Reply[sourceView], error) {
err := m.store.SetDisplayName(ctx, m.orgID, in.Name, strings.TrimSpace(in.Body.Name))
if err := sourceWriteError(err); err != nil {
return nil, err
}
return m.sourceReply(ctx, in.Name, "")
}
type deliveryHeaderInput struct {
Name string `path:"name"`
Body struct {
Header string `json:"header" doc:"A header name; empty stops de-duplicating retries by header"`
}
}
func (m *Module) setDeliveryHeader(ctx context.Context, in *deliveryHeaderInput) (*httpapi.Reply[sourceView], error) {
header := strings.TrimSpace(in.Body.Header)
if header != "" {
if len(header) > 128 || !httpguts.ValidHeaderFieldName(header) {
return nil, huma.Error400BadRequest("the delivery header must be an HTTP header name")
}
header = textproto.CanonicalMIMEHeaderKey(header)
}
err := m.store.SetDeliveryHeader(ctx, m.orgID, in.Name, header)
if err := sourceWriteError(err); err != nil {
return nil, err
}
return m.sourceReply(ctx, in.Name, "")
}
type captureInput struct {
Name string `path:"name"`
Body struct {
Capture bool `json:"capture"`
}
}
// setCapture turns the keeping of a source's payloads on or off. A trigger
// that maps the source's payload needs the stored payload, so it blocks
// turning capture off.
func (m *Module) setCapture(ctx context.Context, in *captureInput) (*httpapi.Reply[sourceView], error) {
if !in.Body.Capture {
n, err := m.store.MappedTriggers(ctx, m.orgID, in.Name)
if err != nil {
return nil, huma.Error500InternalServerError("couldn't check the triggers of the source", err)
}
if n > 0 {
return nil, huma.Error409Conflict(fmt.Sprintf("%d trigger(s) of this source read its payload through a mapping, which needs it kept", n))
}
}
err := m.store.SetCapture(ctx, m.orgID, in.Name, in.Body.Capture)
if err := sourceWriteError(err); err != nil {
return nil, err
}
return m.sourceReply(ctx, in.Name, "")
}
type signingInput struct {
Name string `path:"name"`
Body struct {
Signed bool `json:"signed" doc:"True requires an HMAC signature; false asks to take deliveries without one, which a person must approve"`
}
}
func (m *Module) setSigning(ctx context.Context, in *signingInput) (*httpapi.Reply[sourceView], error) {
src, err := m.readSource(ctx, in.Name)
if err != nil {
return nil, err
}
secret := ""
if in.Body.Signed {
if src.HMACHeader == "" {
return nil, huma.Error409Conflict("set the signature header first: edit the source and choose HMAC signature")
}
if len(src.HMACSecretSealed) == 0 {
if secret, err = m.issueSecret(ctx, src); err != nil {
return nil, err
}
}
}
if err := sourceWriteError(m.store.SetSigning(ctx, m.orgID, in.Name, in.Body.Signed)); err != nil {
return nil, err
}
return m.sourceReply(ctx, in.Name, secret)
}
// approveUnsigned accepts that a source takes deliveries with no verification.
func (m *Module) approveUnsigned(ctx context.Context, in *sourceInput) (*httpapi.Reply[sourceView], error) {
approved, err := m.store.ApproveUnsigned(ctx, m.orgID, in.Name)
if err != nil {
return nil, huma.Error500InternalServerError("couldn't approve the source", err)
}
if !approved {
if _, err := m.readSource(ctx, in.Name); err != nil {
return nil, err
}
return nil, huma.Error409Conflict("the source isn't waiting for approval of unsigned deliveries")
}
return m.sourceReply(ctx, in.Name, "")
}
func (m *Module) rotateSecret(ctx context.Context, in *sourceInput) (*httpapi.Reply[sourceView], error) {
src, err := m.readSource(ctx, in.Name)
if err != nil {
return nil, err
}
if src.HMACHeader == "" {
return nil, huma.Error409Conflict("only a source with an HMAC signature header has a secret")
}
secret, err := m.issueSecret(ctx, src)
if err != nil {
return nil, err
}
return m.sourceReply(ctx, in.Name, secret)
}
// issueSecret generates a signing secret, stores it sealed and returns it.
func (m *Module) issueSecret(ctx context.Context, src store.Source) (string, error) {
secret, err := newSecret()
if err != nil {
return "", huma.Error500InternalServerError("couldn't generate a secret", err)
}
sealed, err := m.sealer.Seal(secretLabel(m.orgID, src.Name), []byte(secret))
if err != nil {
return "", huma.Error500InternalServerError("couldn't seal the secret", err)
}
if err := m.store.SetSecret(ctx, m.orgID, src.Name, sealed); err != nil {
return "", huma.Error500InternalServerError("couldn't save the secret", err)
}
return secret, nil
}
// newSecret returns a 256-bit signing secret in hex.
func newSecret() (string, error) {
b := make([]byte, 32)
if _, err := rand.Read(b); err != nil {
return "", fmt.Errorf("generate secret: %w", err)
}
return hex.EncodeToString(b), nil
}
func sourceWriteError(err error) error {
switch {
case err == nil:
return nil
case errors.Is(err, store.ErrNotFound):
return huma.Error404NotFound("no such source")
}
return huma.Error500InternalServerError("couldn't save the source", err)
}
// deleteSource removes a source. A trigger that names it blocks the delete;
// its event types go with it, and the events it stored stay.
func (m *Module) deleteSource(ctx context.Context, in *sourceInput) (*struct{}, error) {
err := m.store.DeleteSource(ctx, m.orgID, in.Name)
switch {
case errors.Is(err, store.ErrNotFound):
return nil, huma.Error404NotFound("no such source")
case errors.Is(err, store.ErrInUse):
return nil, huma.Error409Conflict("the source is still in use: " + err.Error())
case err != nil:
return nil, huma.Error500InternalServerError("couldn't delete the source", err)
}
return nil, nil
}
type triggerInput struct {
Name string `path:"name"`
}
// moveTrigger changes a trigger's state when it is in one of from, and refuses
// otherwise.
func (m *Module) moveTrigger(ctx context.Context, name string, allowed func(store.Trigger) bool, refusal string, approved, enabled bool) (*httpapi.Reply[triggerView], error) {
t, err := m.store.Trigger(ctx, m.orgID, name)
if errors.Is(err, store.ErrNotFound) {
return nil, huma.Error404NotFound("no such trigger")
}
if err != nil {
return nil, huma.Error500InternalServerError("couldn't read the trigger", err)
}
if !allowed(t) {
return nil, huma.Error409Conflict(refusal)
}
if _, err := m.store.SetTriggerState(ctx, m.orgID, name, approved, enabled); err != nil {
return nil, huma.Error500InternalServerError("couldn't save the trigger", err)
}
t.Approved, t.Enabled = approved, enabled
view, err := m.viewOfTrigger(ctx, t)
if err != nil {
return nil, huma.Error500InternalServerError("couldn't read the trigger", err)
}
return httpapi.OK(view), nil
}
func (m *Module) approveTrigger(ctx context.Context, in *triggerInput) (*httpapi.Reply[triggerView], error) {
return m.moveTrigger(ctx, in.Name, func(t store.Trigger) bool { return !t.Approved }, "the trigger isn't waiting for approval", true, true)
}
func (m *Module) pauseTrigger(ctx context.Context, in *triggerInput) (*httpapi.Reply[triggerView], error) {
return m.moveTrigger(ctx, in.Name, func(t store.Trigger) bool { return t.Approved && t.Enabled }, "only an armed trigger can be paused", true, false)
}
// resumeTrigger returns a paused trigger to waiting for approval, so a person
// approves it again before it fires.
func (m *Module) resumeTrigger(ctx context.Context, in *triggerInput) (*httpapi.Reply[triggerView], error) {
return m.moveTrigger(ctx, in.Name, func(t store.Trigger) bool { return t.Approved && !t.Enabled }, "only a paused trigger can be resumed", false, true)
}
// deleteTrigger removes a trigger. It cascades to nothing: the runs it already
// started continue, and the dispatch records that link them to their events stay
// under the trigger's name.
func (m *Module) deleteTrigger(ctx context.Context, in *triggerInput) (*struct{}, error) {
err := m.store.DeleteTrigger(ctx, m.orgID, in.Name)
switch {
case errors.Is(err, store.ErrNotFound):
return nil, huma.Error404NotFound("no such trigger")
case err != nil:
return nil, huma.Error500InternalServerError("couldn't delete the trigger", err)
}
return nil, nil
}
type triggerDispatchesInput struct {
Name string `path:"name"`
Limit int `query:"limit" minimum:"1" maximum:"200" default:"50"`
}
func (m *Module) triggerDispatches(ctx context.Context, in *triggerDispatchesInput) (*httpapi.Reply[[]dispatchView], error) {
rows, err := m.store.DispatchesOf(ctx, m.orgID, in.Name, in.Limit)
if err != nil {
return nil, huma.Error500InternalServerError("couldn't list the runs of the trigger", err)
}
out := make([]dispatchView, 0, len(rows))
for _, r := range rows {
out = append(out, dispatchView{EventID: r.EventID, RunID: r.RunID, Trigger: in.Name, CreatedAt: r.CreatedAt})
}
return httpapi.OK(out), nil
}