Files
archie/modules/connectors/connector.go
T

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
}