From 14060675cdec9162231cb54d176ce562a9643c85 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 21 Nov 2026 17:14:00 +1100 Subject: [PATCH] feat(connectors): check workflow and trigger references against declared capabilities (#2087) --- api/openapi.yaml | 54 ++++++++ internal/app/archie/operations.go | 2 +- .../00046_connectors_capabilities.sql | 9 ++ modules/connectors/capabilities.go | 106 +++++++++++++++ modules/connectors/connector.go | 6 + modules/connectors/internal/store/store.go | 28 +++- modules/connectors/list.go | 9 ++ modules/connectors/module.go | 16 +++ modules/connectors/remove_test.go | 9 ++ modules/deliveries/deliveries.go | 7 - modules/events/api.go | 34 +++++ modules/events/events.go | 4 +- modules/events/trigger_test.go | 70 ++++++++++ modules/runs/capabilities.go | 128 ++++++++++++++++++ modules/runs/interpreter.go | 3 + modules/runs/message.go | 3 - modules/runs/runs.go | 24 +--- modules/runs/steps_test.go | 50 +++++-- ui/src/lib/api.ts | 19 +++ ui/src/settings/ExtensionList.vue | 22 ++- 20 files changed, 555 insertions(+), 48 deletions(-) create mode 100644 internal/platform/pg/migrations/00046_connectors_capabilities.sql create mode 100644 modules/connectors/capabilities.go create mode 100644 modules/events/trigger_test.go create mode 100644 modules/runs/capabilities.go diff --git a/api/openapi.yaml b/api/openapi.yaml index 579ffa668..1a20ddaa0 100644 --- a/api/openapi.yaml +++ b/api/openapi.yaml @@ -331,6 +331,58 @@ components: - method - request type: object + ConnectorsCapabilities: + additionalProperties: false + properties: + actions: + items: + $ref: "#/components/schemas/ConnectorsCapability" + type: + - array + - "null" + deliveries: + items: + $ref: "#/components/schemas/ConnectorsCapability" + type: + - array + - "null" + events: + items: + $ref: "#/components/schemas/ConnectorsCapability" + type: + - array + - "null" + listens: + type: boolean + lookups: + items: + $ref: "#/components/schemas/ConnectorsCapability" + type: + - array + - "null" + target_facts: + type: boolean + required: + - events + - actions + - deliveries + - lookups + - listens + - target_facts + type: object + ConnectorsCapability: + additionalProperties: false + properties: + description: + type: string + name: + type: string + schema: {} + required: + - name + - description + - schema + type: object ConnectorsCredentialKind: additionalProperties: false properties: @@ -445,6 +497,8 @@ components: type: - array - "null" + capabilities: + $ref: "#/components/schemas/ConnectorsCapabilities" contract: type: string credentials: diff --git a/internal/app/archie/operations.go b/internal/app/archie/operations.go index 025617a20..d559082fc 100644 --- a/internal/app/archie/operations.go +++ b/internal/app/archie/operations.go @@ -59,7 +59,7 @@ func (o *operations) Start(ctx context.Context) error { // from the request. o.engine.Use(runs.Deps{ Settings: o.settings, Toolbox: o.conns, Judge: o.judge, Approver: o.allow, - Notifier: o.tell, Messenger: o.tell, Memory: o.remember, + Notifier: o.tell, Messenger: o.tell, Memory: o.remember, Capabilities: o.conns, }) if err := installStarter(ctx, o.engine); err != nil { return err diff --git a/internal/platform/pg/migrations/00046_connectors_capabilities.sql b/internal/platform/pg/migrations/00046_connectors_capabilities.sql new file mode 100644 index 000000000..006ad33ed --- /dev/null +++ b/internal/platform/pg/migrations/00046_connectors_capabilities.sql @@ -0,0 +1,9 @@ +-- +goose Up +-- What a connector declared when it last loaded: its event types, actions, +-- deliveries and lookups. Workflows and triggers are checked against it when +-- they are saved. Null means the connector has never loaded. The value stays +-- when the connector stops. +ALTER TABLE connectors.accepted ADD COLUMN capabilities jsonb; + +-- +goose Down +ALTER TABLE connectors.accepted DROP COLUMN capabilities; diff --git a/modules/connectors/capabilities.go b/modules/connectors/capabilities.go new file mode 100644 index 000000000..69341ee07 --- /dev/null +++ b/modules/connectors/capabilities.go @@ -0,0 +1,106 @@ +package connectors + +import ( + "context" + "encoding/json/jsontext" + json "encoding/json/v2" + "fmt" + "slices" + "strings" + + pb "github.com/samcharles93/archie-core/internal/contracts/connector/v1" +) + +// 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 +// others take. +type Capability struct { + Name string `json:"name"` + Description string `json:"description"` + Schema jsontext.Value `json:"schema"` +} + +// CheckInput reports why input doesn't match the declared schema, or nil. +func (c Capability) CheckInput(input jsontext.Value) error { + schema, err := compile(c.Schema) + if err != nil { + return fmt.Errorf("%q: %w", c.Name, err) + } + return validate(schema, input) +} + +// Capabilities is what a connector declared when it last loaded. It is stored +// with the accepted connector, so it stays available while the connector is +// stopped. +type Capabilities struct { + Events []Capability `json:"events"` + Actions []Capability `json:"actions"` + Deliveries []Capability `json:"deliveries"` + Lookups []Capability `json:"lookups"` + // Listens says the connector streams events from its own connection to a + // source. + Listens bool `json:"listens"` + // TargetFacts says the connector answers target fact requests. + TargetFacts bool `json:"target_facts"` +} + +// Event returns the named event type. +func (c Capabilities) Event(name string) (Capability, bool) { return find(c.Events, name) } + +// Action returns the named action. +func (c Capabilities) Action(name string) (Capability, bool) { return find(c.Actions, name) } + +// Delivery returns the named delivery. +func (c Capabilities) Delivery(name string) (Capability, bool) { return find(c.Deliveries, name) } + +// Lookup returns the named lookup. +func (c Capabilities) Lookup(name string) (Capability, bool) { return find(c.Lookups, name) } + +func find(list []Capability, name string) (Capability, bool) { + i := slices.IndexFunc(list, func(c Capability) bool { return c.Name == name }) + if i < 0 { + return Capability{}, false + } + return list[i], true +} + +// capabilitiesOf lists what a connector described, each kind in name order. +func capabilitiesOf(desc *pb.DescribeResponse) Capabilities { + caps := Capabilities{ + Events: make([]Capability, 0, len(desc.GetEvents())), + Actions: make([]Capability, 0, len(desc.GetActions())), + Deliveries: make([]Capability, 0, len(desc.GetDeliveries())), + Lookups: make([]Capability, 0, len(desc.GetLookups())), + Listens: desc.GetListens(), + TargetFacts: desc.GetTargetFacts(), + } + for _, e := range desc.GetEvents() { + caps.Events = append(caps.Events, Capability{Name: e.GetName(), Description: e.GetDescription(), Schema: schemaOrEmpty(e.GetSchema())}) + } + for _, a := range desc.GetActions() { + caps.Actions = append(caps.Actions, Capability{Name: a.GetName(), Description: a.GetDescription(), Schema: schemaOrEmpty(a.GetInputSchema())}) + } + for _, d := range desc.GetDeliveries() { + caps.Deliveries = append(caps.Deliveries, Capability{Name: d.GetName(), Description: d.GetDescription(), Schema: schemaOrEmpty(d.GetInputSchema())}) + } + for _, l := range desc.GetLookups() { + caps.Lookups = append(caps.Lookups, Capability{Name: l.GetName(), Description: l.GetDescription(), Schema: schemaOrEmpty(l.GetInputSchema())}) + } + for _, list := range [][]Capability{caps.Events, caps.Actions, caps.Deliveries, caps.Lookups} { + slices.SortFunc(list, func(a, b Capability) int { return strings.Compare(a.Name, b.Name) }) + } + return caps +} + +// Capabilities returns what the named connector declared when it last loaded. +// ok is false when the connector isn't accepted or has never loaded. +func (m *Module) Capabilities(ctx context.Context, connector string) (caps Capabilities, ok bool, err error) { + raw, ok, err := m.store.Capabilities(ctx, m.orgID, connector) + if err != nil || !ok { + return Capabilities{}, false, err + } + if err := json.Unmarshal(raw, &caps); err != nil { + return Capabilities{}, false, fmt.Errorf("connector %q: stored capabilities: %w", connector, err) + } + return caps, true, nil +} diff --git a/modules/connectors/connector.go b/modules/connectors/connector.go index 508b48e5d..04fa73e20 100644 --- a/modules/connectors/connector.go +++ b/modules/connectors/connector.go @@ -157,6 +157,8 @@ type Connector struct { facts bool // settings is the schema it declared for its operator settings. settings []Setting + // caps is everything it declared, in the form that is stored. + caps Capabilities } // open configures a connector and reads its declaration. @@ -180,6 +182,7 @@ func open(ctx context.Context, name string, client pb.ConnectorServiceClient, se listens: desc.GetListens(), facts: desc.GetTargetFacts(), settings: connectorSettings(desc.GetSettings()), + caps: capabilitiesOf(desc), } if err := validateSettingsSchema(c.settings); err != nil { return nil, fmt.Errorf("connector %q: %w", name, err) @@ -337,6 +340,9 @@ func (c *Connector) Declarations() []Declaration { return out } +// Capabilities is everything the connector declared when it loaded. +func (c *Connector) Capabilities() Capabilities { return c.caps } + // Name is the connector's accepted name. func (c *Connector) Name() string { return c.name } diff --git a/modules/connectors/internal/store/store.go b/modules/connectors/internal/store/store.go index 9a45f0418..6b7c5b7f1 100644 --- a/modules/connectors/internal/store/store.go +++ b/modules/connectors/internal/store/store.go @@ -36,6 +36,9 @@ type Accepted struct { // Tools are the lookups and actions an MCP server's acceptance declares, // as a JSON array. Tools jsontext.Value `db:"tools"` + // Capabilities is what a connector declared when it last loaded, as a JSON + // object. It is nil until then, and acceptance never changes it. + Capabilities jsontext.Value `db:"capabilities"` } // Contracts an accepted package can serve. @@ -104,7 +107,7 @@ func New(db *sqlx.DB) *Store { return &Store{db: db} } func (s *Store) List(ctx context.Context, orgID string) ([]Accepted, error) { var out []Accepted if err := s.db.SelectContext(ctx, &out, ` - SELECT org_id, name, path, sha256, egress, env, settings, contract, credentials, args, url, tools + SELECT org_id, name, path, sha256, egress, env, settings, contract, credentials, args, url, tools, capabilities FROM connectors.accepted WHERE org_id = $1 ORDER BY name`, orgID); err != nil { return nil, fmt.Errorf("list connectors: %w", err) } @@ -129,6 +132,29 @@ func (s *Store) Upsert(ctx context.Context, a Accepted) error { return nil } +// SetCapabilities records what an accepted connector declared when it loaded. +func (s *Store) SetCapabilities(ctx context.Context, orgID, name string, capabilities jsontext.Value) error { + if _, err := s.db.ExecContext(ctx, ` + UPDATE connectors.accepted SET capabilities = $3 WHERE org_id = $1 AND name = $2`, orgID, name, []byte(capabilities)); err != nil { + return fmt.Errorf("store capabilities of %q: %w", name, err) + } + return nil +} + +// Capabilities returns what the named connector declared when it last loaded. +// ok is false when it isn't accepted or has never loaded. +func (s *Store) Capabilities(ctx context.Context, orgID, name string) (raw jsontext.Value, ok bool, err error) { + err = s.db.GetContext(ctx, &raw, ` + SELECT capabilities FROM connectors.accepted WHERE org_id = $1 AND name = $2 AND capabilities IS NOT NULL`, orgID, name) + if errors.Is(err, sql.ErrNoRows) { + return nil, false, nil + } + if err != nil { + return nil, false, fmt.Errorf("read capabilities of %q: %w", name, err) + } + return raw, true, nil +} + // Delete removes an accepted package and reports whether there was one. Its // credential slots live on the row, so they go with it. func (s *Store) Delete(ctx context.Context, orgID, name string) (bool, error) { diff --git a/modules/connectors/list.go b/modules/connectors/list.go index f0644ef61..728dad199 100644 --- a/modules/connectors/list.go +++ b/modules/connectors/list.go @@ -34,6 +34,9 @@ type ExtensionView struct { SettingsSchema []Setting `json:"settings_schema"` Credentials map[string]string `json:"credentials"` Tools jsontext.Value `json:"tools,omitempty"` + // Capabilities is what a connector declared when it last loaded. It is + // absent for other packages and for a connector that has never loaded. + Capabilities *Capabilities `json:"capabilities,omitempty"` } // list returns the accepted packages of one contract, in name order. @@ -76,6 +79,12 @@ func (m *Module) viewOf(a store.Accepted) (ExtensionView, error) { return ExtensionView{}, fmt.Errorf("credentials: %w", err) } } + if len(a.Capabilities) > 0 { + view.Capabilities = new(Capabilities) + if err := json.Unmarshal(a.Capabilities, view.Capabilities); err != nil { + return ExtensionView{}, fmt.Errorf("capabilities: %w", err) + } + } state, reason, version, schema := m.stateOf(a) view.State, view.Error, view.Version, view.SettingsSchema = state, reason, version, schema return view, nil diff --git a/modules/connectors/module.go b/modules/connectors/module.go index 58bce3103..d1d1f4593 100644 --- a/modules/connectors/module.go +++ b/modules/connectors/module.go @@ -56,6 +56,8 @@ type registry interface { Credential(ctx context.Context, orgID, name string) (store.Credential, bool, error) Credentials(ctx context.Context, orgID string) ([]store.Credential, error) PutCredential(ctx context.Context, c store.Credential) error + SetCapabilities(ctx context.Context, orgID, name string, capabilities jsontext.Value) error + Capabilities(ctx context.Context, orgID, name string) (jsontext.Value, bool, error) } // Sealing is the age identity credentials are sealed with, and the backup @@ -463,6 +465,10 @@ func (m *Module) launch(ctx context.Context, a store.Accepted) error { if err != nil { return m.fail(ctx, a.Name, err) } + if err := m.storeCapabilities(ctx, c); err != nil { + m.host.Stop(a.Name) + return m.fail(ctx, a.Name, err) + } m.mu.Lock() m.running[a.Name] = c delete(m.failed, a.Name) @@ -471,6 +477,16 @@ func (m *Module) launch(ctx context.Context, a store.Accepted) error { return nil } +// storeCapabilities records what a connector declared, so workflows and +// triggers can be checked against it while the connector is stopped. +func (m *Module) storeCapabilities(ctx context.Context, c *Connector) error { + raw, err := json.Marshal(c.Capabilities()) + if err != nil { + return fmt.Errorf("encode capabilities: %w", err) + } + return m.store.SetCapabilities(ctx, m.orgID, c.Name(), raw) +} + // refSuffix marks a setting that names a secret rather than holding one. The // host resolves it through the named engine, so the extension never reads the // reference. diff --git a/modules/connectors/remove_test.go b/modules/connectors/remove_test.go index b9de7180a..fb00d7dd2 100644 --- a/modules/connectors/remove_test.go +++ b/modules/connectors/remove_test.go @@ -2,6 +2,7 @@ package connectors import ( "context" + "encoding/json/jsontext" json "encoding/json/v2" "errors" "log/slog" @@ -53,6 +54,14 @@ func (f *fakeRegistry) Credentials(context.Context, string) ([]store.Credential, func (f *fakeRegistry) PutCredential(context.Context, store.Credential) error { return nil } +func (f *fakeRegistry) SetCapabilities(context.Context, string, string, jsontext.Value) error { + return nil +} + +func (f *fakeRegistry) Capabilities(context.Context, string, string) (jsontext.Value, bool, error) { + return nil, false, nil +} + // TestRemovingAPackage guards the credential boundary of removal: a secret // engine that a stored credential still resolves through is refused and named, // so no credential is left unresolvable; anything else is removed once, and a diff --git a/modules/deliveries/deliveries.go b/modules/deliveries/deliveries.go index a76b0126d..dd8f878b0 100644 --- a/modules/deliveries/deliveries.go +++ b/modules/deliveries/deliveries.go @@ -140,13 +140,6 @@ func (m *Module) Notify(ctx context.Context, n Notification) error { }) } -// Reaches reports whether channel is a running connector that declares the -// delivery to one chat. -func (m *Module) Reaches(channel string) bool { - c, ok := m.channels.Get(channel) - return ok && c.Delivers(deliveryChat) -} - // Send delivers text to one chat on the named channel, and returns when the // channel has accepted it. The key makes the delivery idempotent on the // channel, so a step that is replayed after a crash does not send twice. diff --git a/modules/events/api.go b/modules/events/api.go index 6576c7365..5ae200e97 100644 --- a/modules/events/api.go +++ b/modules/events/api.go @@ -6,6 +6,7 @@ import ( "encoding/json/jsontext" json "encoding/json/v2" "errors" + "fmt" "net/http" "strconv" "time" @@ -201,6 +202,9 @@ func (m *Module) putTrigger(ctx context.Context, in *putTriggerInput) (*httpapi. } return nil, huma.Error500InternalServerError("couldn't check the workflow", err) } + if err := m.checkEventType(ctx, req.Source, req.EventType); err != nil { + return nil, err + } filter, err := json.Marshal(req.Filter) if err != nil { return nil, huma.Error400BadRequest(err.Error()) @@ -214,6 +218,36 @@ func (m *Module) putTrigger(ctx context.Context, in *putTriggerInput) (*httpapi. return httpapi.OK(triggerSaved{Trigger: in.Name}), nil } +// checkEventType refuses a trigger on an event type that the source's +// connector doesn't declare, so the trigger can't be saved when it could never +// fire. Schedule triggers have no connector. +func (m *Module) checkEventType(ctx context.Context, source, eventType string) error { + if source == scheduleSource { + return nil + } + refuse := func(location, message string) error { + return huma.Error400BadRequest(message, &huma.ErrorDetail{Location: location, Message: message}) + } + src, err := m.reader.Source(ctx, m.orgID, source) + if errors.Is(err, store.ErrNotFound) { + return refuse("body.source", fmt.Sprintf("no source named %q", source)) + } + if err != nil { + return huma.Error500InternalServerError("couldn't read the source", err) + } + caps, ok, err := m.connectors.Capabilities(ctx, src.Connector) + if err != nil { + return huma.Error500InternalServerError("couldn't read what the connector declares", err) + } + if !ok { + return refuse("body.event_type", fmt.Sprintf("connector %q isn't accepted or has never loaded, so its event types aren't known", src.Connector)) + } + if _, declared := caps.Event(eventType); !declared { + return refuse("body.event_type", fmt.Sprintf("connector %q declares no event type %q", src.Connector, eventType)) + } + return nil +} + type putKeyFieldsInput struct { Name string `path:"name"` Body struct { diff --git a/modules/events/events.go b/modules/events/events.go index e7191b17e..834cfb11f 100644 --- a/modules/events/events.go +++ b/modules/events/events.go @@ -33,9 +33,11 @@ import ( var validName = regexp.MustCompile(`^[a-z][a-z0-9-]{0,62}$`) -// Connectors finds the running connector a source reads with. +// 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 diff --git a/modules/events/trigger_test.go b/modules/events/trigger_test.go new file mode 100644 index 000000000..95c301757 --- /dev/null +++ b/modules/events/trigger_test.go @@ -0,0 +1,70 @@ +package events + +import ( + "context" + "errors" + "testing" + + "github.com/danielgtaylor/huma/v2" + + "github.com/samcharles93/archie-core/modules/connectors" + "github.com/samcharles93/archie-core/modules/events/internal/store" +) + +type declaredEvents struct { + Connectors + caps map[string]connectors.Capabilities +} + +func (d declaredEvents) Capabilities(_ context.Context, connector string) (connectors.Capabilities, bool, error) { + caps, ok := d.caps[connector] + return caps, ok, nil +} + +type oneSource struct{ connector string } + +func (o oneSource) Source(_ context.Context, _, name string) (store.Source, error) { + if name != "alerts" { + return store.Source{}, store.ErrNotFound + } + return store.Source{Name: name, Connector: o.connector}, nil +} + +// TestSavingATriggerChecksItsEventType guards the trigger contract: a trigger +// on an event type its source's connector doesn't declare is refused when it +// is saved, because it could never fire. A schedule has no connector and is +// never checked. +func TestSavingATriggerChecksItsEventType(t *testing.T) { + caps := map[string]connectors.Capabilities{ + "pager": {Events: []connectors.Capability{{Name: "incident.opened"}}}, + } + tests := []struct { + name string + source string + connector string + eventType string + wantAt string + }{ + {name: "a declared event type is accepted", source: "alerts", connector: "pager", eventType: "incident.opened"}, + {name: "an undeclared event type is refused", source: "alerts", connector: "pager", eventType: "incident.closed", wantAt: "body.event_type"}, + {name: "a connector that never loaded is refused", source: "alerts", connector: "other", eventType: "incident.opened", wantAt: "body.event_type"}, + {name: "an unknown source is refused", source: "missing", connector: "pager", eventType: "incident.opened", wantAt: "body.source"}, + {name: "a schedule is exempt", source: scheduleSource, connector: "pager", eventType: scheduleType}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + m := &Module{reader: oneSource{connector: tt.connector}, connectors: declaredEvents{caps: caps}} + err := m.checkEventType(t.Context(), tt.source, tt.eventType) + if tt.wantAt == "" { + if err != nil { + t.Fatalf("checkEventType: %v", err) + } + return + } + var refused *huma.ErrorModel + if !errors.As(err, &refused) || refused.Status != 400 || len(refused.Errors) != 1 || refused.Errors[0].Location != tt.wantAt { + t.Fatalf("checkEventType error = %#v, want a 400 at %s", err, tt.wantAt) + } + }) + } +} diff --git a/modules/runs/capabilities.go b/modules/runs/capabilities.go new file mode 100644 index 000000000..dd838e942 --- /dev/null +++ b/modules/runs/capabilities.go @@ -0,0 +1,128 @@ +package runs + +import ( + "context" + json "encoding/json/v2" + "fmt" + "strings" + + "gopkg.in/yaml.v3" + + "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 +// 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) { + switch step.Type { + case typeAction: + return e.checkAction(ctx, index, step) + case typeMessage: + return e.checkMessageChannel(ctx, 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 (e *Engine) checkAction(ctx context.Context, index int, step Step) ([]Problem, error) { + var s actionSettings + if !decodesValid(step, &s) { + 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) + 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, ok := caps.Action(s.Name) + if !ok { + 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 (e *Engine) checkMessageChannel(ctx context.Context, index int, step Step) ([]Problem, error) { + var s messageSettings + if !decodes(step, &s) || strings.TrimSpace(s.Channel) == "" { + return nil, nil + } + caps, ok, err := e.capabilitiesOf(ctx, s.Channel) + if err != nil { + return nil, err + } + if _, declares := caps.Delivery(chatDelivery); 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 +} diff --git a/modules/runs/interpreter.go b/modules/runs/interpreter.go index 6063ae8cb..cbe59adb1 100644 --- a/modules/runs/interpreter.go +++ b/modules/runs/interpreter.go @@ -100,6 +100,9 @@ type Deps struct { Notifier Notifier Messenger Messenger Memory Memory + // Capabilities is what saving a workflow checks connector references + // against. + Capabilities Capabilities } // Workflow is a document ready to run: the code that executes its steps for diff --git a/modules/runs/message.go b/modules/runs/message.go index c845abc19..07bc4cca5 100644 --- a/modules/runs/message.go +++ b/modules/runs/message.go @@ -9,9 +9,6 @@ import ( // Messenger delivers text to one chat on a messaging channel. type Messenger interface { - // Reaches reports whether channel is running and can send to a chat. A - // workflow that sends through any other channel can't be saved. - Reaches(channel string) bool Send(ctx context.Context, channel, chatID, text, key string) error } diff --git a/modules/runs/runs.go b/modules/runs/runs.go index 06a6b6ce3..afb89f546 100644 --- a/modules/runs/runs.go +++ b/modules/runs/runs.go @@ -144,9 +144,11 @@ func (e *Engine) validateDocument(ctx context.Context, body string) (Document, e } var problems []Problem for i, step := range doc.Steps { - if step.Type == typeMessage { - problems = append(problems, e.checkMessageChannel(i, step)...) + found, err := e.checkStepCapabilities(ctx, i, step) + if err != nil { + return Document{}, err } + problems = append(problems, found...) if step.Type != typeAgent { continue } @@ -174,24 +176,6 @@ func (e *Engine) validateDocument(ctx context.Context, body string) (Document, e return doc, nil } -// checkMessageChannel refuses a message.send step whose channel can't send to -// a chat, 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) checkMessageChannel(index int, step Step) []Problem { - var s messageSettings - if decodeSettings(step.Settings, &s) != nil || strings.TrimSpace(s.Channel) == "" { - return nil - } - deps, err := e.steps() - if err == nil && deps.Messenger != nil && deps.Messenger.Reaches(s.Channel) { - return 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), - }} -} - // Has reports whether a workflow is stored under name. func (e *Engine) Has(ctx context.Context, orgID, name string) (bool, error) { _, err := e.db.Workflow(ctx, orgID, name, 0) diff --git a/modules/runs/steps_test.go b/modules/runs/steps_test.go index 1c74bbcbe..4ec3419b5 100644 --- a/modules/runs/steps_test.go +++ b/modules/runs/steps_test.go @@ -16,6 +16,7 @@ import ( "github.com/samcharles93/ai-sdk/chat" "github.com/samcharles93/archie-core/modules/approvals" + "github.com/samcharles93/archie-core/modules/connectors" "github.com/samcharles93/archie-core/modules/deliveries" "github.com/samcharles93/archie-core/modules/governance" "github.com/samcharles93/archie-core/modules/judgement" @@ -113,8 +114,6 @@ func (n *notices) Notify(_ context.Context, msg deliveries.Notification) error { // to a chat is "chat", as a connector declaring the chat delivery would be. type chats struct{ sent []string } -func (*chats) Reaches(channel string) bool { return channel == "chat" } - func (c *chats) Send(_ context.Context, channel, chatID, text, _ string) error { if channel != "chat" { return fmt.Errorf("connector %q declares no chat delivery", channel) @@ -517,23 +516,48 @@ steps: } } -// TestSavingChecksMessageChannel guards the message.send contract: a workflow -// that sends through a channel no accepted connector declares the chat -// delivery for is refused when it is saved, not when it runs. -func TestSavingChecksMessageChannel(t *testing.T) { +// declared is the capabilities connectors have declared, by connector name. +type declared map[string]connectors.Capabilities + +func (d declared) Capabilities(_ context.Context, connector string) (connectors.Capabilities, bool, error) { + caps, ok := d[connector] + return caps, ok, nil +} + +// TestSavingChecksConnectorReferences guards the workflow step contract at +// save time: a connector.action or message.send step that names an action, +// input or channel its connector doesn't declare is refused when the workflow +// is saved, not when it runs. An input that holds a reference can't be checked +// until the run starts, so it is skipped. +func TestSavingChecksConnectorReferences(t *testing.T) { + caps := declared{ + "host": {Actions: []connectors.Capability{{ + Name: "clean", + Schema: jsontext.Value(`{"type":"object","properties":{"host":{"type":"string"}},"required":["host"]}`), + }}}, + "chat": {Deliveries: []connectors.Capability{{Name: "chat_message"}}}, + "mail": {Deliveries: []connectors.Capability{{Name: "message"}}}, + } tests := []struct { - name string - channel string - want string + name string + step string + want string }{ - {name: "a channel that sends to a chat is accepted", channel: "chat"}, - {name: "a channel with no chat delivery is refused", channel: "mail", want: `steps[0].settings.channel: channel "mail" isn't an accepted connector that sends messages to a chat`}, + {name: "a declared action with a matching input is accepted", step: "{type: connector.action, settings: {connector: host, name: clean, input: {host: web-1}}}"}, + {name: "an undeclared action is refused", step: "{type: connector.action, settings: {connector: host, name: reboot}}", want: `steps[0].settings.name: connector "host" declares no action "reboot"`}, + {name: "a connector that never loaded is refused", step: "{type: connector.action, settings: {connector: gone, name: clean}}", want: `steps[0].settings.name: connector "gone" isn't accepted or has never loaded`}, + {name: "an input that fails the schema is refused", step: "{type: connector.action, settings: {connector: host, name: clean, input: {host: 3}}}", want: `steps[0].settings.input: input for action "clean"`}, + {name: "a missing required input is refused", step: "{type: connector.action, settings: {connector: host, name: clean}}", want: "steps[0].settings.input"}, + {name: "an input with a reference is not checked", step: `{type: connector.action, settings: {connector: host, name: clean, input: {other: "{{ inputs.event.fields.host }}"}}}`}, + {name: "a channel that sends to a chat is accepted", step: "{type: message.send, settings: {channel: chat, chat_id: ops, text: hi}}"}, + {name: "a channel with no chat delivery is refused", step: "{type: message.send, settings: {channel: mail, chat_id: ops, text: hi}}", want: `steps[0].settings.channel: channel "mail" isn't an accepted connector that sends messages to a chat`}, + {name: "an unknown channel is refused", step: "{type: message.send, settings: {channel: gone, chat_id: ops, text: hi}}", want: `steps[0].settings.channel: channel "gone"`}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { engine := newEngine(nil, &fakeWork{}, slog.New(slog.DiscardHandler), Options{}) - engine.Use(Deps{Settings: onePersonPath{}, Messenger: &chats{}}) - _, err := engine.validateDocument(t.Context(), "steps:\n - {type: message.send, settings: {channel: "+tt.channel+", chat_id: ops, text: hi}}\n") + engine.Use(Deps{Settings: onePersonPath{}, Messenger: &chats{}, Capabilities: caps}) + _, err := engine.validateDocument(t.Context(), "inputs: {event: {type: object}}\nsteps:\n - "+tt.step+"\n") switch { case tt.want == "" && err != nil: t.Fatalf("validateDocument: %v", err) diff --git a/ui/src/lib/api.ts b/ui/src/lib/api.ts index bdafcc93a..2df7a47d2 100644 --- a/ui/src/lib/api.ts +++ b/ui/src/lib/api.ts @@ -816,6 +816,23 @@ export interface SettingField { secret?: boolean; } +/** One event type, action, delivery or lookup a connector declared. */ +export interface Capability { + name: string; + description: string; + schema: unknown; +} + +/** What a connector declared when it last loaded. */ +export interface Capabilities { + events: Capability[]; + actions: Capability[]; + deliveries: Capability[]; + lookups: Capability[]; + listens: boolean; + target_facts: boolean; +} + export interface Extension { name: string; state: string; @@ -834,6 +851,8 @@ export interface Extension { credentials?: Record; /** An MCP server's declared tools, as it was accepted with them. */ tools?: unknown; + /** A connector's declarations; absent until it has loaded. */ + capabilities?: Capabilities; } export interface ExtensionInput { diff --git a/ui/src/settings/ExtensionList.vue b/ui/src/settings/ExtensionList.vue index fb369490e..68aca4ea9 100644 --- a/ui/src/settings/ExtensionList.vue +++ b/ui/src/settings/ExtensionList.vue @@ -29,13 +29,25 @@ const props = defineProps<{ kind: ExtensionKind; noun: string }>(); const { data, error, reload } = useRead(() => api.extensions(props.kind)); onMounted(reload); -const columns: DataTableColumn[] = [ +const columns = computed[]>(() => [ { id: "name", label: "Name", fixed: true, sort: (e) => e.name }, { id: "state", label: "State", fixed: true, sort: (e) => e.state }, { id: "version", label: "Version", sort: (e) => e.version ?? "" }, + ...(props.kind === "connectors" ? [{ id: "capabilities", label: "Declares" }] : []), { id: "path", label: "Path", hidden: true }, { id: "egress", label: "Egress", hidden: true }, -]; +]); + +const CAPABILITY_GROUPS = [ + { key: "events", label: "Events" }, + { key: "actions", label: "Actions" }, + { key: "deliveries", label: "Deliveries" }, + { key: "lookups", label: "Lookups" }, +] as const; + +function declared(ext: Extension) { + return CAPABILITY_GROUPS.map((g) => ({ ...g, items: ext.capabilities?.[g.key] ?? [] })).filter((g) => g.items.length); +} const mcp = computed(() => props.kind === "mcp-servers"); const editing = ref(false); @@ -129,6 +141,12 @@ async function remove(): Promise {

{{ row.error }}

+