connector

Documentation

Overview

Package connector defines the SPI for execution connectors.

A connector bridges the control plane to an external system — a payment processor, a git provider, a calendar service, etc. When the policy engine allows an action (or a human approves it), the control plane selects the appropriate connector and calls Execute.

Each connector implementation is responsible for one external system. The SPI is intentionally narrow: connectors receive a bounded execution request and return a result. Credential injection and parameter bounding happen in the control plane before the connector is called.

Index

• type Connector
• type ExecutionRequest
• type ExecutionResult
• type ExecutionStatus
• type InjectedCredential
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Get(ctx context.Context, connectorType, provider string) (Connector, bool)
  • func (r *Registry) Register(ctx context.Context, c Connector)

Types

type Connector

type Connector interface {
	// Type returns the connector type identifier (e.g. "payments", "git",
	// "calendar"). Used by the registry to route execution requests.
	Type() string

	// Provider returns the specific provider name (e.g. "stripe", "github",
	// "google_calendar"). Multiple connectors may share a Type.
	Provider() string

	// Execute runs the action described by the request.
	Execute(ctx context.Context, req ExecutionRequest) (ExecutionResult, error)
}

Connector executes an approved action against an external system.

type ExecutionRequest

type ExecutionRequest struct {
	GrantID     string
	IntentID    string
	ConnectorID string
	// ActionType is the dot-namespaced action, e.g. "payment.charge".
	ActionType string
	// Parameters are the bounded, approved parameters for execution.
	// These are constrained by the execution grant and may differ from
	// the original intent if a human modified them during approval.
	Parameters map[string]any
	// Credential is the injected secret for this connector, resolved from
	// the vault. Connectors must not store or log this value.
	Credential *InjectedCredential
}

ExecutionRequest is passed to a connector when executing an approved action.

type ExecutionResult

type ExecutionResult struct {
	Status     ExecutionStatus
	Output     map[string]any
	ReceiptRef string
	Error      string
}

ExecutionResult is returned by a connector after execution.

type ExecutionStatus

type ExecutionStatus string

ExecutionStatus is the outcome of a connector execution.

const (
	ExecutionStatusSucceeded ExecutionStatus = "succeeded"
	ExecutionStatusFailed    ExecutionStatus = "failed"
	ExecutionStatusCancelled ExecutionStatus = "cancelled"
)

type InjectedCredential

type InjectedCredential struct {
	Type  string
	Value []byte
}

InjectedCredential carries a resolved secret for use during execution. Connectors receive this transiently and must not persist it.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds the registered connectors and routes execution requests. It is safe for concurrent use.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty connector registry.

func (*Registry) Get

func (r *Registry) Get(ctx context.Context, connectorType, provider string) (Connector, bool)

Get returns the connector for the given type and provider.

func (*Registry) Register

func (r *Registry) Register(ctx context.Context, c Connector)

Register adds a connector to the registry. The key is "<type>/<provider>", e.g. "payments/stripe".