Files
archie/modules/events/events.go
T
sam e3130d53e7 Merge branch 'worktree-agent-a82ec64b6cc1a2809'
# Conflicts:
#	internal/app/archie/operations.go
#	modules/events/events.go
#	modules/governance/accounts_api.go
#	modules/governance/governance.go
2026-11-22 02:16:56 +11:00

584 lines
21 KiB
Go

// Package events is how Archie hears: sources deliver payloads, a connector
// turns each verified payload into typed events, and every event is stored
// before it is acknowledged. A source whose connector holds its own connection
// (a chat long poll) streams its events instead, resuming from a stored
// cursor. A dispatcher then claims each new event, settles an approval it
// answers, links a resolve to what it resolves, and starts a run for every
// trigger it matches.
package events
import (
"context"
"crypto/rand"
"encoding/hex"
"encoding/json/jsontext"
json "encoding/json/v2"
"errors"
"fmt"
"log/slog"
"net"
"net/http"
"regexp"
"strings"
"sync"
"time"
"github.com/google/uuid"
"github.com/jmoiron/sqlx"
"github.com/samcharles93/archie-core/internal/platform/httpjson"
"github.com/samcharles93/archie-core/modules/approvals"
"github.com/samcharles93/archie-core/modules/connectors"
"github.com/samcharles93/archie-core/modules/events/internal/match"
"github.com/samcharles93/archie-core/modules/events/internal/store"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/runs"
)
var validName = regexp.MustCompile(`^[a-z][a-z0-9-]{0,62}$`)
// Connectors finds the running connector a source reads with, and says what a
// connector declared when it last loaded.
type Connectors interface {
Get(name string) (*connectors.Connector, bool)
Capabilities(ctx context.Context, connector string) (connectors.Capabilities, bool, error)
}
// Runs starts runs for matched triggers, and says whether a trigger could
// start its workflow.
type Runs interface {
Start(ctx context.Context, req runs.StartRequest) (uuid.UUID, error)
CheckTrigger(ctx context.Context, orgID, workflow string) error
}
// Deliveries recognises the echo of a message Archie sent. It returns the run
// that sent the message the ids name on channel, which is nil when the message
// belonged to no run.
type Deliveries interface {
SentBy(ctx context.Context, channel string, ids ...string) (run uuid.UUID, found bool, err error)
// Send writes text to one chat on a channel.
Send(ctx context.Context, channel, chatID, text, key string) error
}
// Answers settles the approval requests answer events name.
type Answers interface {
Settle(ctx context.Context, id uuid.UUID, who governance.Subject, via string, approved bool) (bool, error)
}
// Links binds the channel accounts that account.link events name to the
// accounts that issued their codes.
type Links interface {
CompleteLink(ctx context.Context, issuer, subject, name, code string) (governance.Identity, error)
// LinkingURL is the dashboard page where a person links a channel account.
LinkingURL(ctx context.Context) (string, error)
}
// The events a channel emits. An answer carries the approval request and the
// person's decision; a link carries the code the person sent to the channel.
// Both name the sender as "<connector>:<channel user id>" in by, and may name
// the chat to reply to in chat_id.
const (
answerType = "approval.answer"
linkType = "account.link"
)
// listenRetry is how long a listener waits after its stream breaks.
const listenRetry = 5 * time.Second
// Module hears events for one organisation.
type Module struct {
orgID string
store *store.Store
reader sourceReader
inserter eventInserter
delivery governance.DeliveryAuthorizer
sealer Sealer
parse func(ctx context.Context, connector string, body []byte, headers map[string]string) ([]connectors.Event, error)
connectors Connectors
runs Runs
answers Answers
links Links
deliveries Deliveries
log *slog.Logger
poll time.Duration
}
// NewModule returns the events module for orgID.
func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, sealer Sealer, c Connectors, r Runs, a Answers, l Links, d Deliveries) *Module {
st := store.New(db)
m := &Module{orgID: orgID, store: st, reader: st, inserter: st, sealer: sealer, connectors: c, runs: r, answers: a, links: l, deliveries: d, log: log, poll: time.Second}
m.parse = m.parseWith
return m
}
// sourceReader is the store method that intake uses to look up a source.
type sourceReader interface {
Source(ctx context.Context, orgID, name string) (store.Source, error)
}
// eventInserter stores an event, and reports false when its source event id
// was stored before.
type eventInserter interface {
Insert(ctx context.Context, e store.Event) (isNew bool, err error)
}
// UseDeliveryPolicy gives intake the policy that decides, per source and
// sender address, who may deliver. Until it is set every delivery is refused.
func (m *Module) UseDeliveryPolicy(d governance.DeliveryAuthorizer) { m.delivery = d }
// Routes adds the webhook intake. It stays outside the API because each
// source verifies its own deliveries.
func (m *Module) Routes(mux *http.ServeMux) {
mux.HandleFunc("POST /hooks/{source}", m.intake)
}
// intake verifies a delivery, checks the source's delivery policy, parses it
// with the source's connector and stores each event before responding. A
// redelivered event violates a uniqueness constraint, is counted as a
// duplicate and is not dispatched again.
func (m *Module) intake(w http.ResponseWriter, r *http.Request) {
src, parsed, body, status, err := m.accept(r)
if err != nil {
httpjson.Error(w, status, err.Error())
return
}
stored, duplicates, err := m.save(r.Context(), src, parsed, body)
if err != nil {
httpjson.Error(w, http.StatusServiceUnavailable, err.Error())
return
}
httpjson.Write(w, http.StatusAccepted, map[string]int{"stored": stored, "duplicates": duplicates})
}
// accept verifies a delivery against its source's scheme, then passes it to
// the connector for parsing. A delivery that fails verification is rejected
// with 401 before the connector sees its body, and the rejection is logged.
// An unknown source and a failed verification get the same response, so a
// caller cannot use it to discover source names.
func (m *Module) accept(r *http.Request) (src store.Source, parsed []connectors.Event, body []byte, status int, err error) {
ctx := r.Context()
src, err = m.reader.Source(ctx, m.orgID, r.PathValue("source"))
if errors.Is(err, store.ErrNotFound) {
return src, nil, nil, http.StatusUnauthorized, errUnknown
}
if err != nil {
return src, nil, nil, http.StatusServiceUnavailable, errors.New("events store unavailable")
}
// A token is checked before the body is read. A signature covers the body,
// so it is checked on the raw bytes as soon as they are read.
switch src.Verification {
case store.Token:
if err := checkToken(src, r); err != nil {
return m.refuse(ctx, src, err)
}
case store.HMAC, store.None:
default:
return m.refuse(ctx, src, fmt.Errorf("unknown verification %q", src.Verification))
}
body, err = httpjson.Body(r)
if err != nil {
return src, nil, nil, http.StatusRequestEntityTooLarge, err
}
if src.Verification == store.HMAC {
if err := m.verifyHMAC(src, r.Header, body); err != nil {
return m.refuse(ctx, src, err)
}
}
if status, err := m.deliveryAllowed(ctx, src, r); err != nil {
return src, nil, nil, status, err
}
parsed, err = m.parse(ctx, src.Connector, body, map[string]string{"Content-Type": r.Header.Get("Content-Type")})
if errors.Is(err, errConnectorDown) {
return src, nil, nil, http.StatusServiceUnavailable, err
}
if err != nil {
return src, nil, nil, http.StatusBadRequest, err
}
return src, parsed, body, 0, nil
}
var (
errUnknown = errors.New("unknown source or failed verification")
errConnectorDown = errors.New("connector isn't running")
)
// refuse logs why a delivery was rejected and chooses the status: 401 when
// verification failed, 503 when verification could not run.
func (m *Module) refuse(ctx context.Context, src store.Source, err error) (store.Source, []connectors.Event, []byte, int, error) {
m.log.WarnContext(ctx, "refused webhook delivery", "source", src.Name, "verification", src.Verification, "reason", err.Error())
if errors.Is(err, errUnverified) {
return src, nil, nil, http.StatusUnauthorized, errUnknown
}
return src, nil, nil, http.StatusServiceUnavailable, errors.New("couldn't verify the delivery")
}
var (
errDeliveryDenied = errors.New("delivery not permitted")
errDeliveryUnavailable = errors.New("delivery policy unavailable")
)
// deliveryAllowed applies the source's delivery policy to the sender's address.
// A verified delivery still needs it. When the policy chain can't decide the
// delivery is refused with 503, so the sender retries and nothing is stored.
func (m *Module) deliveryAllowed(ctx context.Context, src store.Source, r *http.Request) (int, error) {
if m.delivery == nil {
return http.StatusServiceUnavailable, errDeliveryUnavailable
}
addr, _, err := net.SplitHostPort(r.RemoteAddr)
if err != nil {
addr = r.RemoteAddr
}
// Delivery policies belong to the operating organisation, whatever the
// source's own org id says.
d := m.delivery.AuthorizeDelivery(ctx, governance.DefaultOrgID, src.Name, addr)
switch {
case d.Allowed:
return 0, nil
case errors.Is(d.Err, governance.ErrChainUnavailable):
m.log.WarnContext(ctx, "delivery policy unavailable", "source", src.Name)
return http.StatusServiceUnavailable, errDeliveryUnavailable
}
m.log.WarnContext(ctx, "refused webhook delivery", "source", src.Name, "reason", "delivery policy", "level", d.Level, "policies", d.Policies)
return http.StatusForbidden, errDeliveryDenied
}
// parseWith has a running connector parse a delivery.
func (m *Module) parseWith(ctx context.Context, connector string, body []byte, headers map[string]string) ([]connectors.Event, error) {
conn, ok := m.connectors.Get(connector)
if !ok {
return nil, fmt.Errorf("connector %s: %w", connector, errConnectorDown)
}
return conn.Parse(ctx, body, headers)
}
// save stores each event with the payload it arrived in, recording at arrival
// whether it echoes a delivery Archie sent, so those never reach grouping.
func (m *Module) save(ctx context.Context, src store.Source, parsed []connectors.Event, body []byte) (stored, duplicates int, err error) {
for _, e := range parsed {
run, own, err := m.deliveries.SentBy(ctx, src.Connector, e.SourceEventID, e.LinkKey)
if err != nil {
return stored, duplicates, fmt.Errorf("check delivery provenance: %w", err)
}
isNew, err := m.inserter.Insert(ctx, newRow(m.orgID, src, e, body, own, run))
if err != nil {
return stored, duplicates, err
}
if isNew {
stored++
} else {
duplicates++
}
}
return stored, duplicates, nil
}
// Work listens to every listening source and dispatches stored events until
// ctx ends.
func (m *Module) Work(ctx context.Context) {
var listeners sync.WaitGroup
defer listeners.Wait()
listening := map[string]bool{}
nextCheck, nextTick := time.Time{}, time.Time{}
for ctx.Err() == nil {
if now := time.Now(); now.After(nextTick) {
if err := m.tick(ctx, now); err != nil && ctx.Err() == nil {
m.log.ErrorContext(ctx, "fire schedules", "error", err)
}
nextTick = now.Add(scheduleCheck)
}
if time.Now().After(nextCheck) {
m.startListeners(ctx, &listeners, listening)
nextCheck = time.Now().Add(listenRetry)
}
found, err := m.store.Dispatch(ctx, m.dispatch)
if err != nil {
m.log.ErrorContext(ctx, "dispatch event", "error", err)
}
if found && err == nil {
continue
}
select {
case <-ctx.Done():
case <-time.After(m.poll):
}
}
}
// startListeners starts one listener for each source whose connector listens
// and has none yet. A listener lives until ctx ends.
func (m *Module) startListeners(ctx context.Context, wg *sync.WaitGroup, listening map[string]bool) {
sources, err := m.store.Sources(ctx, m.orgID)
if err != nil {
m.log.ErrorContext(ctx, "list sources", "error", err)
return
}
for _, src := range sources {
conn, ok := m.connectors.Get(src.Connector)
if listening[src.Name] || !ok || !conn.Listens() {
continue
}
listening[src.Name] = true
wg.Go(func() { m.listen(ctx, src) })
}
}
// listen streams one source's events, storing each batch before its cursor,
// so a restart fetches again anything not yet stored and dedupe drops what
// was. A broken stream is opened again from the stored cursor.
func (m *Module) listen(ctx context.Context, src store.Source) {
cursor := src.Cursor
for ctx.Err() == nil {
conn, ok := m.connectors.Get(src.Connector)
var err error
if !ok {
err = fmt.Errorf("connector %q isn't running", src.Connector)
} else {
err = conn.Listen(ctx, cursor, func(events []connectors.Event, next string) error {
if _, _, err := m.save(ctx, src, events, received(events)); err != nil {
return err
}
if err := m.store.SetCursor(ctx, m.orgID, src.Name, next); err != nil {
return err
}
cursor = next
return nil
})
}
if ctx.Err() != nil {
return
}
m.log.WarnContext(ctx, "listening stopped", "source", src.Name, "error", err)
select {
case <-ctx.Done():
case <-time.After(listenRetry):
}
}
}
// answer settles the approval request an answer event names. An answer that
// can't settle it is logged and done with: the request's own record already
// says why. A channel account no account has linked is told how to link it.
func (m *Module) answer(ctx context.Context, e store.Event) error {
var a struct {
RequestID uuid.UUID `json:"request_id"`
Approved bool `json:"approved"`
By string `json:"by"`
ChatID string `json:"chat_id"`
}
if err := json.Unmarshal(e.Fields, &a); err != nil {
m.log.WarnContext(ctx, "unreadable approval answer", "event", e.ID, "error", err)
return nil
}
src, who, ok := m.sender(ctx, e, a.By)
if !ok {
return nil
}
settled, err := m.answers.Settle(ctx, a.RequestID, who, e.Source, a.Approved)
if errors.Is(err, approvals.ErrUnlinked) {
m.replyUnlinked(ctx, e, src, a.ChatID)
return nil
}
if err != nil {
return fmt.Errorf("settle approval %s: %w", a.RequestID, err)
}
if !settled {
m.log.InfoContext(ctx, "approval answer changed nothing", "event", e.ID, "request", a.RequestID)
}
return nil
}
// link binds the channel account that sent a link code to the account that
// issued the code, and tells the sender how it went. A code that doesn't work
// is not retried.
func (m *Module) link(ctx context.Context, e store.Event) error {
var l struct {
By string `json:"by"`
Code string `json:"code"`
Name string `json:"name"`
ChatID string `json:"chat_id"`
}
if err := json.Unmarshal(e.Fields, &l); err != nil {
m.log.WarnContext(ctx, "unreadable link request", "event", e.ID, "error", err)
return nil
}
src, who, ok := m.sender(ctx, e, l.By)
if !ok {
return nil
}
account, err := m.links.CompleteLink(ctx, who.Issuer, who.Subject, l.Name, l.Code)
switch {
case errors.Is(err, governance.ErrLinkCode):
m.reply(ctx, e, src, l.ChatID, "That link code didn't work. Start again from your account page in the dashboard.")
case errors.Is(err, governance.ErrLinkTaken):
m.reply(ctx, e, src, l.ChatID, "That "+src.Connector+" account is already linked to another account.")
case err != nil:
return fmt.Errorf("link %s account: %w", src.Connector, err)
default:
m.log.InfoContext(ctx, "channel account linked", "event", e.ID, "connector", src.Connector, "account", account.ID)
m.reply(ctx, e, src, l.ChatID, "Linked to "+account.DisplayName+".")
}
return nil
}
// sender reads who sent a channel event. The connector comes from the event's
// source, so a connector can only speak for its own accounts: by must name the
// source's connector.
func (m *Module) sender(ctx context.Context, e store.Event, by string) (store.Source, governance.Subject, bool) {
src, err := m.reader.Source(ctx, e.OrgID, e.Source)
if err != nil {
m.log.WarnContext(ctx, "channel event from an unknown source", "event", e.ID, "source", e.Source, "error", err)
return store.Source{}, governance.Subject{}, false
}
prefix, subject, found := strings.Cut(by, ":")
if !found || prefix != src.Connector || subject == "" {
m.log.WarnContext(ctx, "channel event names a sender outside its connector", "event", e.ID, "source", e.Source)
return store.Source{}, governance.Subject{}, false
}
return src, governance.Subject{Issuer: src.Connector, Subject: subject}, true
}
// replyUnlinked tells an unlinked channel account where to link it.
func (m *Module) replyUnlinked(ctx context.Context, e store.Event, src store.Source, chatID string) {
url, err := m.links.LinkingURL(ctx)
if err != nil {
m.log.WarnContext(ctx, "read the linking URL", "event", e.ID, "error", err)
return
}
m.reply(ctx, e, src, chatID, "That "+src.Connector+" account isn't linked to an account, so your answer wasn't counted. Link it at "+url+" and answer again.")
}
// reply sends text to the chat an event came from. A reply that fails is
// logged and dropped: the event itself is already handled.
func (m *Module) reply(ctx context.Context, e store.Event, src store.Source, chatID, text string) {
if chatID == "" {
return
}
if err := m.deliveries.Send(ctx, src.Connector, chatID, text, "reply:"+e.ID.String()); err != nil {
m.log.WarnContext(ctx, "reply to a channel event", "event", e.ID, "error", err)
}
}
// dispatch links a resolve to the event it resolves and starts no work for
// it. Any other event starts one run per matching trigger, keyed so a retried
// dispatch never starts a second run.
func (m *Module) dispatch(tx *sqlx.Tx, e store.Event) (bool, error) {
ctx := context.Background()
if e.Own {
// Archie's own message coming back starts nothing and proposes nothing.
return false, nil
}
switch e.Type {
case answerType:
return false, m.answer(ctx, e)
case linkType:
return false, m.link(ctx, e)
}
linked, err := store.Link(ctx, tx, e)
if err != nil || linked {
return false, err
}
triggers, err := store.Triggers(ctx, tx, e.OrgID, e.Source, e.Type)
if err != nil {
return false, err
}
matched, refused := false, false
for _, t := range triggers {
var filter map[string]string
if err := json.Unmarshal(t.Filter, &filter); err != nil {
return false, fmt.Errorf("trigger %q filter: %w", t.Name, err)
}
if !match.Fields(e.Fields, filter) {
continue
}
runID, started, err := m.startRun(ctx, e, t)
if err != nil {
return false, err
}
if !started {
refused = true
continue
}
if err := store.RecordDispatch(ctx, tx, e.ID, t.Name, runID); err != nil {
return false, err
}
m.log.InfoContext(ctx, "trigger started run", "event", e.ID, "trigger", t.Name, "run", runID)
matched = true
}
if !matched && !refused {
return false, m.noteUnmatched(ctx, tx, e)
}
return matched, nil
}
// noteUnmatched files an event no trigger took into a group for review.
func (m *Module) noteUnmatched(ctx context.Context, tx *sqlx.Tx, e store.Event) error {
created, err := store.NoteUnmatched(ctx, tx, e)
if err != nil {
return err
}
if created {
m.log.InfoContext(ctx, "unmatched events started a group", "source", e.Source, "type", e.Type)
}
return nil
}
// startRun starts the run trigger t asks for, as the workload principal, so
// the start is decided by the same policy chain as any other caller. A refusal
// is final: it reports no run and no error, and the trigger is skipped. A policy
// chain that can't decide returns an error instead, which rolls the dispatch
// back so the event stays queued and is dispatched again.
func (m *Module) startRun(ctx context.Context, e store.Event, t store.Trigger) (runID uuid.UUID, started bool, err error) {
ctx = governance.WithPrincipal(ctx, governance.WorkloadPrincipal(governance.DefaultOrgID))
runID, err = m.runs.Start(ctx, runs.StartRequest{
OrgID: e.OrgID, Workflow: t.Workflow, Key: e.ID.String() + ":" + t.Name, Input: runInput(e),
})
if errors.Is(err, governance.ErrDenied) {
m.log.WarnContext(ctx, "trigger not permitted to start its workflow", "event", e.ID, "trigger", t.Name, "error", err)
return uuid.Nil, false, nil
}
if err != nil {
return uuid.Nil, false, fmt.Errorf("start run for trigger %q: %w", t.Name, err)
}
return runID, true, nil
}
// Origin returns the event and trigger that started a run.
func (m *Module) Origin(ctx context.Context, runID uuid.UUID) (runs.Origin, bool, error) {
o, ok, err := m.store.OriginOf(ctx, m.orgID, runID)
if err != nil || !ok {
return runs.Origin{}, ok, err
}
return runs.Origin{
EventID: o.EventID, Source: o.Source, Type: o.Type, Fields: o.Fields,
ReceivedAt: o.ReceivedAt, Trigger: o.Trigger, Filter: o.Filter,
}, true, nil
}
func runInput(e store.Event) jsontext.Value {
input, err := json.Marshal(map[string]any{"event": map[string]any{
"id": e.ID, "source": e.Source, "type": e.Type, "fields": e.Fields, "occurred_at": e.OccurredAt.Time,
}})
if err != nil {
return jsontext.Value("null")
}
return input
}
func newToken() (string, error) {
b := make([]byte, 32)
if _, err := rand.Read(b); err != nil {
return "", fmt.Errorf("generate token: %w", err)
}
return hex.EncodeToString(b), nil
}
// received renders a batch a listening connector streamed, so the stored body
// is what reached the run rather than only the fields parsed from it.
func received(events []connectors.Event) []byte {
body, err := json.Marshal(events)
if err != nil {
return nil
}
return body
}