feat(connectors): re-check saved workflows on capability change; validate core delivery schemas (#2091, #2092)

When a connector loads with new declarations, the saved workflows that
reference it are re-checked against them (via a Recheck hook wired to
runs.Engine.RecheckConnector); if any would become invalid, the new
declarations are refused and the connector fails to start, so the breakage
surfaces at update time instead of mid-run. The previous declarations stay
in force.

A connector that declares the message or chat_message delivery now has its
declared input schema checked against every payload shape core sends on it
when it loads; a rejecting schema fails the connector. The delivery names
are exported from the connectors module and used by core's senders, so the
contract has one definition.
This commit is contained in:
sam committed 2026-11-21 18:34:47 +11:00
1 parent d318f912a8
commit 592d36e0d1
7 files changed
+312 -27

No files matched your search

+6
View File
@@ -64,6 +64,12 @@ func (o *operations) Start(ctx context.Context) error {
if err := installStarter(ctx, o.engine); err != nil { if err := installStarter(ctx, o.engine); err != nil {
return err return err
} }
// A connector's new declarations are re-checked against the saved
// workflows that reference it, so an update that would break them is
// refused instead of failing a run later.
o.conns.Use(func(ctx context.Context, connector string, caps connectors.Capabilities) error {
return o.engine.RecheckConnector(ctx, orgID, connector, caps)
})
if err := o.conns.Start(ctx); err != nil { if err := o.conns.Start(ctx); err != nil {
return fmt.Errorf("read accepted connectors: %w", err) return fmt.Errorf("read accepted connectors: %w", err)
} }
+42
View File
@@ -11,6 +11,48 @@ import (
pb "github.com/samcharles93/archie-core/internal/contracts/connector/v1" pb "github.com/samcharles93/archie-core/internal/contracts/connector/v1"
) )
// The deliveries core itself sends on a channel connector. They are part of
// the extension contract: a connector that declares one must declare a schema
// that accepts what core sends.
const (
DeliveryMessage = "message"
DeliveryChatMessage = "chat_message"
)
// coreDeliveries lists, for each delivery core sends itself, every payload
// shape core may put in it: a message always has a title, and may also carry
// a body and, for an approval request, its request id; a chat message always
// has a chat id and text.
var coreDeliveries = map[string][]jsontext.Value{
DeliveryMessage: {
jsontext.Value(`{"title":"a title"}`),
jsontext.Value(`{"title":"a title","body":"a body"}`),
jsontext.Value(`{"title":"a title","approval_request_id":"00000000-0000-0000-0000-000000000000"}`),
jsontext.Value(`{"title":"a title","body":"a body","approval_request_id":"00000000-0000-0000-0000-000000000000"}`),
},
DeliveryChatMessage: {
jsontext.Value(`{"chat_id":"a chat","text":"a message"}`),
},
}
// checkCoreDeliveries refuses a declaration of a delivery core sends itself
// whose input schema rejects a payload core sends, so the mismatch surfaces
// when the connector loads rather than when a delivery is mid-flight.
func checkCoreDeliveries(caps Capabilities) error {
for _, name := range []string{DeliveryMessage, DeliveryChatMessage} {
d, ok := caps.Delivery(name)
if !ok {
continue
}
for _, payload := range coreDeliveries[name] {
if err := d.CheckInput(payload); err != nil {
return fmt.Errorf("delivery %q doesn't accept what core sends: %w", name, err)
}
}
}
return nil
}
// Capability is one event type, action, delivery or lookup a connector // Capability is one event type, action, delivery or lookup a connector
// declared. Schema is the JSON Schema of an event's fields or of the input the // declared. Schema is the JSON Schema of an event's fields or of the input the
// others take. // others take.
+64
View File
@@ -0,0 +1,64 @@
package connectors
import (
"encoding/json/jsontext"
"strings"
"testing"
)
// TestCoreDeliveriesGuardWhatCoreSends guards the load-time check of a
// connector's declared message and chat_message schemas: a declaration that
// rejects a payload core sends is refused, so the mismatch surfaces when the
// connector loads rather than when a delivery is mid-flight. A connector that
// declares neither delivery, or declares one that accepts core's payloads, is
// fine.
func TestCoreDeliveriesGuardWhatCoreSends(t *testing.T) {
accepting := jsontext.Value(`{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"},"approval_request_id":{"type":"string"}},"required":["title"]}`)
tests := []struct {
name string
deliveries []Capability
want string
}{
{
name: "a message schema that accepts core's payloads passes",
deliveries: []Capability{
{Name: DeliveryMessage, Schema: accepting},
{Name: DeliveryChatMessage, Schema: jsontext.Value(`{"type":"object","properties":{"chat_id":{"type":"string"},"text":{"type":"string"}},"required":["chat_id","text"]}`)},
},
},
{
name: "a message schema requiring a field core never sends is refused",
deliveries: []Capability{{Name: DeliveryMessage, Schema: jsontext.Value(`{"type":"object","required":["to"]}`)}},
want: `delivery "message" doesn't accept what core sends`,
},
{
name: "a message schema with a wrong field type is refused",
deliveries: []Capability{{Name: DeliveryMessage, Schema: jsontext.Value(`{"type":"object","properties":{"title":{"type":"integer"}}}`)}},
want: `delivery "message" doesn't accept what core sends`,
},
{
name: "a chat_message schema that rejects core's payload is refused",
deliveries: []Capability{{Name: DeliveryChatMessage, Schema: jsontext.Value(`{"type":"object","properties":{"chat_id":{"type":"string"},"text":{"type":"integer"}},"required":["chat_id","text"]}`)}},
want: `delivery "chat_message" doesn't accept what core sends`,
},
{
name: "an empty schema accepts anything",
deliveries: []Capability{{Name: DeliveryMessage, Schema: jsontext.Value(`{}`)}},
},
{
name: "a connector that declares neither core delivery is not checked",
deliveries: []Capability{{Name: "webhook", Schema: jsontext.Value(`{"type":"object","required":["url"]}`)}},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := checkCoreDeliveries(Capabilities{Deliveries: tt.deliveries})
switch {
case tt.want == "" && err != nil:
t.Fatalf("checkCoreDeliveries: %v", err)
case tt.want != "" && (err == nil || !strings.Contains(err.Error(), tt.want)):
t.Fatalf("checkCoreDeliveries error = %v, want %q", err, tt.want)
}
})
}
}
+37
View File
@@ -46,6 +46,20 @@ type Module struct {
servers map[string]*Server servers map[string]*Server
stops map[string]context.CancelFunc stops map[string]context.CancelFunc
failed map[string]string failed map[string]string
// recheck, when set, re-checks saved configuration against a connector's
// new declarations; an error refuses them.
recheck Recheck
}
// Recheck re-checks saved configuration against the capabilities a connector
// now declares. An error refuses the new declarations.
type Recheck func(ctx context.Context, connector string, caps Capabilities) error
// Use sets the hook called when a connector's declarations change.
func (m *Module) Use(recheck Recheck) {
m.mu.Lock()
defer m.mu.Unlock()
m.recheck = recheck
} }
// registry is the module's persistence, so removal can be tested with a fake. // registry is the module's persistence, so removal can be tested with a fake.
@@ -465,6 +479,10 @@ func (m *Module) launch(ctx context.Context, a store.Accepted) error {
if err != nil { if err != nil {
return m.fail(ctx, a.Name, err) return m.fail(ctx, a.Name, err)
} }
if err := m.checkDeclarations(ctx, a.Name, c.Capabilities()); err != nil {
m.host.Stop(a.Name)
return m.fail(ctx, a.Name, err)
}
if err := m.storeCapabilities(ctx, c); err != nil { if err := m.storeCapabilities(ctx, c); err != nil {
m.host.Stop(a.Name) m.host.Stop(a.Name)
return m.fail(ctx, a.Name, err) return m.fail(ctx, a.Name, err)
@@ -477,6 +495,25 @@ func (m *Module) launch(ctx context.Context, a store.Accepted) error {
return nil return nil
} }
// checkDeclarations refuses declarations core can't work with before they are
// stored: a reserved delivery whose schema rejects what core sends, or saved
// configuration that the new declarations break. The connector's previous
// declarations stay in force.
func (m *Module) checkDeclarations(ctx context.Context, name string, caps Capabilities) error {
if err := checkCoreDeliveries(caps); err != nil {
return err
}
m.mu.RLock()
recheck := m.recheck
m.mu.RUnlock()
if recheck != nil {
if err := recheck(ctx, name, caps); err != nil {
return fmt.Errorf("saved configuration doesn't match the new declarations: %w", err)
}
}
return nil
}
// storeCapabilities records what a connector declared, so workflows and // storeCapabilities records what a connector declared, so workflows and
// triggers can be checked against it while the connector is stopped. // triggers can be checked against it while the connector is stopped.
func (m *Module) storeCapabilities(ctx context.Context, c *Connector) error { func (m *Module) storeCapabilities(ctx context.Context, c *Connector) error {
+4 -9
View File
@@ -35,12 +35,7 @@ const (
topicComposer = "composer" topicComposer = "composer"
pageSize = 100 pageSize = 100
heartbeat = 25 * time.Second heartbeat = 25 * time.Second
// deliveryMessage is the delivery a connector declares to carry messages. maxBackoff = 10 * time.Minute
deliveryMessage = "message"
// deliveryChat is the delivery a connector declares to send text to one
// chat it can address.
deliveryChat = "chat_message"
maxBackoff = 10 * time.Minute
// maxAttempts ends a delivery that keeps failing: with the backoff capped // maxAttempts ends a delivery that keeps failing: with the backoff capped
// at maxBackoff it is about a day of trying. // at maxBackoff it is about a day of trying.
maxAttempts = 150 maxAttempts = 150
@@ -152,7 +147,7 @@ func (m *Module) Send(ctx context.Context, channel, chatID, text, key string) er
if err != nil { if err != nil {
return err return err
} }
if _, err := c.Deliver(ctx, deliveryChat, raw, key); err != nil { if _, err := c.Deliver(ctx, connectors.DeliveryChatMessage, raw, key); err != nil {
return fmt.Errorf("send to %s chat %s: %w", channel, chatID, err) return fmt.Errorf("send to %s chat %s: %w", channel, chatID, err)
} }
return nil return nil
@@ -192,7 +187,7 @@ func (m *Module) send(ctx context.Context, msg store.Message) error {
if created { if created {
m.hub.Publish(hub.Note{Topic: topicComposer, Seq: seq}) m.hub.Publish(hub.Note{Topic: topicComposer, Seq: seq})
} }
for _, c := range m.channels.Delivering(deliveryMessage) { for _, c := range m.channels.Delivering(connectors.DeliveryMessage) {
// Each channel keeps its own row, so each carries its own id. // Each channel keeps its own row, so each carries its own id.
row := msg row := msg
row.ID, row.Channel, row.Sent = uuid.New(), c.Name(), false row.ID, row.Channel, row.Sent = uuid.New(), c.Name(), false
@@ -283,7 +278,7 @@ func (m *Module) sendTo(ctx context.Context, msg store.Message) (string, error)
if err != nil { if err != nil {
return "", err return "", err
} }
return c.Deliver(ctx, deliveryMessage, raw, msg.Key) return c.Deliver(ctx, connectors.DeliveryMessage, raw, msg.Key)
} }
// backoff is how long to wait after the attempts so far before the next. // backoff is how long to wait after the attempts so far before the next.
+97 -18
View File
@@ -4,6 +4,7 @@ import (
"context" "context"
json "encoding/json/v2" json "encoding/json/v2"
"fmt" "fmt"
"slices"
"strings" "strings"
"gopkg.in/yaml.v3" "gopkg.in/yaml.v3"
@@ -11,9 +12,6 @@ import (
"github.com/samcharles93/archie-core/modules/connectors" "github.com/samcharles93/archie-core/modules/connectors"
) )
// chatDelivery is the delivery a connector declares to send text to one chat.
const chatDelivery = "chat_message"
// Capabilities reports what a connector declared when it last loaded. ok is // Capabilities reports what a connector declared when it last loaded. ok is
// false when the connector isn't accepted or has never loaded. // false when the connector isn't accepted or has never loaded.
type Capabilities interface { type Capabilities interface {
@@ -38,11 +36,45 @@ func (e *Engine) capabilitiesOf(ctx context.Context, connector string) (connecto
// is saved instead of when it runs. A step with invalid settings is already // is saved instead of when it runs. A step with invalid settings is already
// reported by the document check. // reported by the document check.
func (e *Engine) checkStepCapabilities(ctx context.Context, index int, step Step) ([]Problem, error) { func (e *Engine) checkStepCapabilities(ctx context.Context, index int, step Step) ([]Problem, error) {
connector := stepConnector(step)
if connector == "" {
return nil, nil
}
caps, ok, err := e.capabilitiesOf(ctx, connector)
if err != nil {
return nil, err
}
return stepProblems(caps, ok, index, step)
}
// stepConnector is the connector a step calls: an action step's connector, or
// a message step's channel. Empty when the step calls none, or its settings
// don't decode, which the document check already reports.
func stepConnector(step Step) string {
switch step.Type { switch step.Type {
case typeAction: case typeAction:
return e.checkAction(ctx, index, step) var s actionSettings
if decodes(step, &s) {
return s.Connector
}
case typeMessage: case typeMessage:
return e.checkMessageChannel(ctx, index, step) var s messageSettings
if decodes(step, &s) {
return s.Channel
}
}
return ""
}
// stepProblems checks one step against the capabilities its connector
// declares, so a connector.action or message.send step that names something
// the connector doesn't declare fails here rather than when it runs.
func stepProblems(caps connectors.Capabilities, ok bool, index int, step Step) ([]Problem, error) {
switch step.Type {
case typeAction:
return actionProblems(caps, ok, index, step)
case typeMessage:
return messageProblems(caps, ok, index, step)
} }
return nil, nil return nil, nil
} }
@@ -58,21 +90,17 @@ func decodesValid(step Step, target interface{ valid() error }) bool {
return decodes(step, target) && target.valid() == nil return decodes(step, target) && target.valid() == nil
} }
func (e *Engine) checkAction(ctx context.Context, index int, step Step) ([]Problem, error) { func actionProblems(caps connectors.Capabilities, ok bool, index int, step Step) ([]Problem, error) {
var s actionSettings var s actionSettings
if !decodesValid(step, &s) { if !decodesValid(step, &s) {
return nil, nil return nil, nil
} }
caps, ok, err := e.capabilitiesOf(ctx, s.Connector)
if err != nil {
return nil, err
}
name := fmt.Sprintf("steps[%d].settings.name", index) name := fmt.Sprintf("steps[%d].settings.name", index)
if !ok { if !ok {
return []Problem{{Path: name, Message: fmt.Sprintf("connector %q isn't accepted or has never loaded, so its actions aren't known", s.Connector)}}, nil return []Problem{{Path: name, Message: fmt.Sprintf("connector %q isn't accepted or has never loaded, so its actions aren't known", s.Connector)}}, nil
} }
declared, ok := caps.Action(s.Name) declared, declaredOK := caps.Action(s.Name)
if !ok { if !declaredOK {
return []Problem{{Path: name, Message: fmt.Sprintf("connector %q declares no action %q", s.Connector, s.Name)}}, nil return []Problem{{Path: name, Message: fmt.Sprintf("connector %q declares no action %q", s.Connector, s.Name)}}, nil
} }
if referencesInput(s.Input) { if referencesInput(s.Input) {
@@ -109,16 +137,12 @@ func referencesInput(input map[string]any) bool {
return found return found
} }
func (e *Engine) checkMessageChannel(ctx context.Context, index int, step Step) ([]Problem, error) { func messageProblems(caps connectors.Capabilities, ok bool, index int, step Step) ([]Problem, error) {
var s messageSettings var s messageSettings
if !decodes(step, &s) || strings.TrimSpace(s.Channel) == "" { if !decodes(step, &s) || strings.TrimSpace(s.Channel) == "" {
return nil, nil return nil, nil
} }
caps, ok, err := e.capabilitiesOf(ctx, s.Channel) if _, declares := caps.Delivery(connectors.DeliveryChatMessage); ok && declares {
if err != nil {
return nil, err
}
if _, declares := caps.Delivery(chatDelivery); ok && declares {
return nil, nil return nil, nil
} }
return []Problem{{ return []Problem{{
@@ -126,3 +150,58 @@ func (e *Engine) checkMessageChannel(ctx context.Context, index int, step Step)
Message: fmt.Sprintf("channel %q isn't an accepted connector that sends messages to a chat", s.Channel), Message: fmt.Sprintf("channel %q isn't an accepted connector that sends messages to a chat", s.Channel),
}}, nil }}, nil
} }
// RecheckConnector re-checks every saved workflow that references connector
// against caps, the declarations it now makes, and returns the problems found.
// It runs when a connector's declarations change, so a saved workflow can't
// silently keep calling something the connector no longer declares.
func (e *Engine) RecheckConnector(ctx context.Context, orgID, connector string, caps connectors.Capabilities) error {
stored, err := e.db.Workflows(ctx, orgID)
if err != nil {
return fmt.Errorf("list workflows: %w", err)
}
bodies := make(map[string]string, len(stored))
for _, w := range stored {
bodies[w.Name] = w.Body
}
problems, err := recheckWorkflows(bodies, connector, caps)
if err != nil {
return err
}
if len(problems) > 0 {
return &InvalidError{Problems: problems}
}
return nil
}
// recheckWorkflows re-checks saved workflow bodies against the declarations a
// connector now makes: each step that calls the connector is checked as it is
// when the workflow is saved, and every problem is pathed by workflow and step.
func recheckWorkflows(bodies map[string]string, connector string, caps connectors.Capabilities) ([]Problem, error) {
names := make([]string, 0, len(bodies))
for name := range bodies {
names = append(names, name)
}
slices.Sort(names)
var problems []Problem
for _, name := range names {
doc, err := ParseDocument(bodies[name])
if err != nil {
continue
}
for i, step := range doc.Steps {
if stepConnector(step) != connector {
continue
}
found, err := stepProblems(caps, true, i, step)
if err != nil {
return nil, err
}
for _, p := range found {
p.Path = name + "." + p.Path
problems = append(problems, p)
}
}
}
return problems, nil
}
+62
View File
@@ -602,3 +602,65 @@ func mustJSON(t *testing.T, v any) string {
} }
return string(b) return string(b)
} }
// TestRecheckingSavedWorkflowsOnCapabilityChange guards the re-check that runs
// when a connector's declarations change: a saved workflow that calls an
// action or channel the connector no longer declares is reported, pathed by
// workflow and step, so the caller can refuse the new declarations. A workflow
// that doesn't reference the connector, or one the new declarations still
// cover, is left alone.
func TestRecheckingSavedWorkflowsOnCapabilityChange(t *testing.T) {
bodies := map[string]string{
"triage": "steps:\n - {type: connector.action, settings: {connector: host, name: clean, input: {host: web-1}}}\n",
"notify": "steps:\n - {type: message.send, settings: {channel: chat, chat_id: ops, text: hi}}\n",
"other": "steps:\n - {type: connector.action, settings: {connector: mail, name: send}}\n",
}
full := connectors.Capabilities{
Actions: []connectors.Capability{{Name: "clean", Schema: jsontext.Value(`{"type":"object","properties":{"host":{"type":"string"}},"required":["host"]}`)}},
Deliveries: []connectors.Capability{{Name: connectors.DeliveryChatMessage}},
}
tests := []struct {
name string
connector string
caps connectors.Capabilities
want []string
}{
{
name: "a saved action the connector no longer declares is reported",
connector: "host",
caps: connectors.Capabilities{Deliveries: full.Deliveries},
want: []string{`triage.steps[0].settings.name: connector "host" declares no action "clean"`},
},
{
name: "a saved channel that no longer sends to a chat is reported",
connector: "chat",
caps: connectors.Capabilities{Actions: full.Actions},
want: []string{`notify.steps[0].settings.channel: channel "chat" isn't an accepted connector that sends messages to a chat`},
},
{
name: "declarations that still cover the saved workflows pass",
connector: "host",
caps: full,
},
{
name: "a connector no saved workflow references passes",
connector: "gone",
caps: connectors.Capabilities{},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
problems, err := recheckWorkflows(bodies, tt.connector, tt.caps)
if err != nil {
t.Fatalf("recheckWorkflows: %v", err)
}
got := make([]string, len(problems))
for i, p := range problems {
got[i] = p.String()
}
if !slices.Equal(got, tt.want) {
t.Fatalf("problems = %q, want %q", got, tt.want)
}
})
}
}