297 lines
9.4 KiB
Go
297 lines
9.4 KiB
Go
package connectors
|
|
|
|
import (
|
|
"context"
|
|
"crypto/sha256"
|
|
"encoding/hex"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"time"
|
|
|
|
"github.com/google/jsonschema-go/jsonschema"
|
|
|
|
pb "github.com/samcharles93/archie-core/internal/contracts/connector/v1"
|
|
)
|
|
|
|
var (
|
|
// ErrDigestMismatch means the connector ran something other than the
|
|
// judged action. It is a finding and tightens the action class.
|
|
ErrDigestMismatch = errors.New("connector executed a different action than the one judged")
|
|
// ErrOutcomeUnknown means the connector can't confirm what its effect did.
|
|
ErrOutcomeUnknown = errors.New("connector can't confirm the outcome")
|
|
// ErrNotIdempotent refuses an action with external effects from a
|
|
// connector that doesn't honour idempotency keys.
|
|
ErrNotIdempotent = errors.New("action has external effects but the connector doesn't declare idempotency")
|
|
// ErrUnknownName names an action, lookup or event type the connector
|
|
// never declared.
|
|
ErrUnknownName = errors.New("not declared by the connector")
|
|
)
|
|
|
|
// Reversibility says whether and how an action can be undone.
|
|
type Reversibility int
|
|
|
|
// Reversibility values, in the order of decreasing autonomy they allow.
|
|
const (
|
|
ReversibilityUnspecified Reversibility = iota
|
|
UndoneAutomatically
|
|
Recoverable
|
|
Irreversible
|
|
)
|
|
|
|
// Effect describes what one action does.
|
|
type Effect struct {
|
|
ReadOnly bool
|
|
Reversibility Reversibility
|
|
Summary string
|
|
}
|
|
|
|
// Target is what an action acts on. Connector, action, kind and environment
|
|
// together are the action class.
|
|
type Target struct {
|
|
Kind string
|
|
ID string
|
|
Environment string
|
|
Disposable bool
|
|
}
|
|
|
|
// Resolution is an action's target and the effect it would have there.
|
|
type Resolution struct {
|
|
Target Target
|
|
Effect Effect
|
|
}
|
|
|
|
// Event is one typed event a connector parsed from a verified payload.
|
|
type Event struct {
|
|
Type string
|
|
SourceEventID string
|
|
Fields json.RawMessage
|
|
LinkKey string
|
|
OccurredAt time.Time
|
|
}
|
|
|
|
// Invocation is one judged action to run.
|
|
type Invocation struct {
|
|
Action string
|
|
Input json.RawMessage
|
|
IdempotencyKey string
|
|
}
|
|
|
|
type action struct {
|
|
effect Effect
|
|
idempotent bool
|
|
input *jsonschema.Resolved
|
|
}
|
|
|
|
// Connector is a running connector and what it declared.
|
|
type Connector struct {
|
|
name string
|
|
client pb.ConnectorServiceClient
|
|
events map[string]*jsonschema.Resolved
|
|
actions map[string]action
|
|
lookups map[string]*jsonschema.Resolved
|
|
}
|
|
|
|
// open configures a connector and reads its declaration.
|
|
func open(ctx context.Context, name string, client pb.ConnectorServiceClient, settings, secrets map[string]string) (*Connector, error) {
|
|
if _, err := client.Configure(ctx, &pb.ConfigureRequest{Settings: settings, Secrets: secrets}); err != nil {
|
|
return nil, fmt.Errorf("connector %q: configure: %w", name, err)
|
|
}
|
|
desc, err := client.Describe(ctx, &pb.DescribeRequest{})
|
|
if err != nil {
|
|
return nil, fmt.Errorf("connector %q: describe: %w", name, err)
|
|
}
|
|
if desc.GetContract() != contractVersion {
|
|
return nil, fmt.Errorf("connector %q speaks contract %q, the host speaks %q", name, desc.GetContract(), contractVersion)
|
|
}
|
|
c := &Connector{
|
|
name: name, client: client,
|
|
events: map[string]*jsonschema.Resolved{},
|
|
actions: map[string]action{},
|
|
lookups: map[string]*jsonschema.Resolved{},
|
|
}
|
|
return c, c.load(desc)
|
|
}
|
|
|
|
func (c *Connector) load(desc *pb.DescribeResponse) error {
|
|
for _, e := range desc.GetEvents() {
|
|
s, err := compile(e.GetSchema())
|
|
if err != nil {
|
|
return fmt.Errorf("connector %q: event %q: %w", c.name, e.GetName(), err)
|
|
}
|
|
c.events[e.GetName()] = s
|
|
}
|
|
for _, a := range desc.GetActions() {
|
|
s, err := compile(a.GetInputSchema())
|
|
if err != nil {
|
|
return fmt.Errorf("connector %q: action %q: %w", c.name, a.GetName(), err)
|
|
}
|
|
c.actions[a.GetName()] = action{effect: effectFrom(a.GetEffect()), idempotent: a.GetIdempotent(), input: s}
|
|
}
|
|
for _, l := range desc.GetLookups() {
|
|
s, err := compile(l.GetInputSchema())
|
|
if err != nil {
|
|
return fmt.Errorf("connector %q: lookup %q: %w", c.name, l.GetName(), err)
|
|
}
|
|
c.lookups[l.GetName()] = s
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// Name is the connector's accepted name.
|
|
func (c *Connector) Name() string { return c.name }
|
|
|
|
// Parse turns a payload the caller has already verified into typed events,
|
|
// each checked against its declared schema.
|
|
func (c *Connector) Parse(ctx context.Context, body []byte, headers map[string]string) ([]Event, error) {
|
|
resp, err := c.client.Parse(ctx, &pb.ParseRequest{Body: body, Headers: headers})
|
|
if err != nil {
|
|
return nil, fmt.Errorf("connector %q: parse: %w", c.name, err)
|
|
}
|
|
events := make([]Event, 0, len(resp.GetEvents()))
|
|
for _, e := range resp.GetEvents() {
|
|
schema, ok := c.events[e.GetType()]
|
|
if !ok {
|
|
return nil, fmt.Errorf("connector %q: event type %q: %w", c.name, e.GetType(), ErrUnknownName)
|
|
}
|
|
if err := validate(schema, e.GetFields()); err != nil {
|
|
return nil, fmt.Errorf("connector %q: event %q: %w", c.name, e.GetType(), err)
|
|
}
|
|
events = append(events, Event{
|
|
Type: e.GetType(), SourceEventID: e.GetSourceEventId(), Fields: e.GetFields(),
|
|
LinkKey: e.GetLinkKey(), OccurredAt: e.GetOccurredAt().AsTime(),
|
|
})
|
|
}
|
|
return events, nil
|
|
}
|
|
|
|
// Resolve returns the target and effect of one concrete action.
|
|
func (c *Connector) Resolve(ctx context.Context, name string, input json.RawMessage) (Resolution, error) {
|
|
if _, err := c.action(name, input); err != nil {
|
|
return Resolution{}, err
|
|
}
|
|
resp, err := c.client.Resolve(ctx, &pb.ResolveRequest{Action: name, Input: input})
|
|
if err != nil {
|
|
return Resolution{}, fmt.Errorf("connector %q: resolve %q: %w", c.name, name, err)
|
|
}
|
|
t := resp.GetTarget()
|
|
return Resolution{
|
|
Target: Target{Kind: t.GetKind(), ID: t.GetId(), Environment: t.GetEnvironment(), Disposable: t.GetDisposable()},
|
|
Effect: effectFrom(resp.GetEffect()),
|
|
}, nil
|
|
}
|
|
|
|
// Invoke runs one judged action and decodes its output into T. The connector
|
|
// must report the digest of what it ran; a different digest is refused.
|
|
func (c *Connector) Invoke[T any](ctx context.Context, inv Invocation) (T, error) {
|
|
var zero T
|
|
a, err := c.action(inv.Action, inv.Input)
|
|
if err != nil {
|
|
return zero, err
|
|
}
|
|
if !a.effect.ReadOnly && !a.idempotent {
|
|
return zero, fmt.Errorf("connector %q: action %q: %w", c.name, inv.Action, ErrNotIdempotent)
|
|
}
|
|
digest := Digest(inv.Action, inv.Input)
|
|
resp, err := c.client.Invoke(ctx, &pb.InvokeRequest{
|
|
Action: inv.Action, Input: inv.Input, IdempotencyKey: inv.IdempotencyKey, Digest: digest,
|
|
})
|
|
if err != nil {
|
|
return zero, fmt.Errorf("connector %q: invoke %q: %w", c.name, inv.Action, err)
|
|
}
|
|
if resp.GetExecutedDigest() != digest {
|
|
return zero, fmt.Errorf("connector %q: action %q: %w", c.name, inv.Action, ErrDigestMismatch)
|
|
}
|
|
if resp.GetOutcomeUnknown() {
|
|
return zero, fmt.Errorf("connector %q: action %q: %w", c.name, inv.Action, ErrOutcomeUnknown)
|
|
}
|
|
return decode[T](resp.GetOutput())
|
|
}
|
|
|
|
// Lookup answers a read-only question and decodes the answer into T. found is
|
|
// false when the connector found nothing, which callers report as a finding.
|
|
func (c *Connector) Lookup[T any](ctx context.Context, name string, input json.RawMessage) (T, bool, error) {
|
|
var zero T
|
|
schema, ok := c.lookups[name]
|
|
if !ok {
|
|
return zero, false, fmt.Errorf("connector %q: lookup %q: %w", c.name, name, ErrUnknownName)
|
|
}
|
|
if err := validate(schema, input); err != nil {
|
|
return zero, false, fmt.Errorf("connector %q: lookup %q: %w", c.name, name, err)
|
|
}
|
|
resp, err := c.client.Lookup(ctx, &pb.LookupRequest{Lookup: name, Input: input})
|
|
if err != nil {
|
|
return zero, false, fmt.Errorf("connector %q: lookup %q: %w", c.name, name, err)
|
|
}
|
|
if !resp.GetFound() {
|
|
return zero, false, nil
|
|
}
|
|
out, err := decode[T](resp.GetOutput())
|
|
return out, err == nil, err
|
|
}
|
|
|
|
func (c *Connector) action(name string, input json.RawMessage) (action, error) {
|
|
a, ok := c.actions[name]
|
|
if !ok {
|
|
return action{}, fmt.Errorf("connector %q: action %q: %w", c.name, name, ErrUnknownName)
|
|
}
|
|
if err := validate(a.input, input); err != nil {
|
|
return action{}, fmt.Errorf("connector %q: action %q: %w", c.name, name, err)
|
|
}
|
|
return a, nil
|
|
}
|
|
|
|
// Digest identifies one concrete action: its name and its exact input. The
|
|
// connector SDK computes the same digest over what it ran.
|
|
func Digest(action string, input json.RawMessage) string {
|
|
h := sha256.New()
|
|
h.Write([]byte(action))
|
|
h.Write([]byte{0})
|
|
h.Write(input)
|
|
return hex.EncodeToString(h.Sum(nil))
|
|
}
|
|
|
|
func effectFrom(e *pb.Effect) Effect {
|
|
return Effect{ReadOnly: e.GetReadOnly(), Reversibility: Reversibility(e.GetReversibility()), Summary: e.GetSummary()}
|
|
}
|
|
|
|
func compile(raw []byte) (*jsonschema.Resolved, error) {
|
|
if len(raw) == 0 {
|
|
raw = []byte(`{}`)
|
|
}
|
|
var s jsonschema.Schema
|
|
if err := json.Unmarshal(raw, &s); err != nil {
|
|
return nil, fmt.Errorf("schema: %w", err)
|
|
}
|
|
resolved, err := s.Resolve(nil)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("schema: %w", err)
|
|
}
|
|
return resolved, nil
|
|
}
|
|
|
|
func validate(schema *jsonschema.Resolved, raw json.RawMessage) error {
|
|
if len(raw) == 0 {
|
|
raw = json.RawMessage(`{}`)
|
|
}
|
|
var instance any
|
|
if err := json.Unmarshal(raw, &instance); err != nil {
|
|
return fmt.Errorf("payload is not JSON: %w", err)
|
|
}
|
|
if err := schema.Validate(instance); err != nil {
|
|
return fmt.Errorf("payload doesn't match its schema: %w", err)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func decode[T any](raw []byte) (T, error) {
|
|
var out T
|
|
if len(raw) == 0 {
|
|
return out, nil
|
|
}
|
|
if err := json.Unmarshal(raw, &out); err != nil {
|
|
return out, fmt.Errorf("decode connector output: %w", err)
|
|
}
|
|
return out, nil
|
|
}
|