Files
archie/modules/runs/capabilities.go
T
sam 592d36e0d1 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.
2026-11-21 18:34:47 +11:00

208 lines
6.5 KiB
Go

package runs
import (
"context"
json "encoding/json/v2"
"fmt"
"slices"
"strings"
"gopkg.in/yaml.v3"
"github.com/samcharles93/archie-core/modules/connectors"
)
// Capabilities reports what a connector declared when it last loaded. ok is
// false when the connector isn't accepted or has never loaded.
type Capabilities interface {
Capabilities(ctx context.Context, connector string) (connectors.Capabilities, bool, error)
}
// capabilitiesOf reads what a connector declared. Without a Capabilities
// dependency no connector has declared anything.
func (e *Engine) capabilitiesOf(ctx context.Context, connector string) (connectors.Capabilities, bool, error) {
deps, err := e.steps()
if err != nil {
return connectors.Capabilities{}, false, err
}
if deps.Capabilities == nil {
return connectors.Capabilities{}, false, nil
}
return deps.Capabilities.Capabilities(ctx, connector)
}
// checkStepCapabilities refuses a connector.action or message.send step that
// names something its connector doesn't declare, so the workflow fails when it
// is saved instead of when it runs. A step with invalid settings is already
// reported by the document check.
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 {
case typeAction:
var s actionSettings
if decodes(step, &s) {
return s.Connector
}
case typeMessage:
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
}
// decodes reports whether a step's settings decode into target. A step that
// doesn't is already reported by the document check.
func decodes(step Step, target any) bool {
return decodeSettings(step.Settings, target) == nil
}
// decodesValid is decodes for settings that must also be valid.
func decodesValid(step Step, target interface{ valid() error }) bool {
return decodes(step, target) && target.valid() == nil
}
func actionProblems(caps connectors.Capabilities, ok bool, index int, step Step) ([]Problem, error) {
var s actionSettings
if !decodesValid(step, &s) {
return nil, nil
}
name := fmt.Sprintf("steps[%d].settings.name", index)
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
}
declared, declaredOK := caps.Action(s.Name)
if !declaredOK {
return []Problem{{Path: name, Message: fmt.Sprintf("connector %q declares no action %q", s.Connector, s.Name)}}, nil
}
if referencesInput(s.Input) {
return nil, nil
}
input, err := json.Marshal(inputOrEmpty(s.Input))
if err != nil {
return nil, fmt.Errorf("encode the input of action %q: %w", s.Name, err)
}
if err := declared.CheckInput(input); err != nil {
return []Problem{{Path: fmt.Sprintf("steps[%d].settings.input", index), Message: fmt.Sprintf("input for action %q: %s", s.Name, err)}}, nil
}
return nil, nil
}
func inputOrEmpty(input map[string]any) map[string]any {
if input == nil {
return map[string]any{}
}
return input
}
// referencesInput reports whether any string in an action's input holds a
// reference, which only has a value once the run starts.
func referencesInput(input map[string]any) bool {
var node yaml.Node
if err := node.Encode(input); err != nil {
return true
}
found := false
walkStrings(&node, func(value string) {
found = found || referencePattern.MatchString(value)
})
return found
}
func messageProblems(caps connectors.Capabilities, ok bool, index int, step Step) ([]Problem, error) {
var s messageSettings
if !decodes(step, &s) || strings.TrimSpace(s.Channel) == "" {
return nil, nil
}
if _, declares := caps.Delivery(connectors.DeliveryChatMessage); ok && declares {
return nil, nil
}
return []Problem{{
Path: fmt.Sprintf("steps[%d].settings.channel", index),
Message: fmt.Sprintf("channel %q isn't an accepted connector that sends messages to a chat", s.Channel),
}}, 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
}