capabilities

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 28, 2024 License: MIT Imports: 11 Imported by: 20

Documentation

Index

Constants

View Source 
const (
	DefaultRegistrationRefresh = 30 * time.Second
	DefaultRegistrationExpiry  = 2 * time.Minute
	DefaultMessageExpiry       = 2 * time.Minute
)

Variables

View Source 
var ErrStopExecution = &errStopExecution{}

Functions

func ExecuteSync added in v0.2.0 

func ExecuteSync(ctx context.Context, c CallbackExecutable, request CapabilityRequest) (*values.List, error)

ExecuteSync executes a capability synchronously. We are not handling a case where a capability panics and crashes. There is default timeout of 10 seconds. If a capability takes longer than that then it should be executed asynchronously.

func ExecuteSyncWithTimeout added in v0.2.0 

func ExecuteSyncWithTimeout(ctx context.Context, c CallbackExecutable, request CapabilityRequest, timeout time.Duration) (*values.List, error)

ExecuteSyncWithTimeout allows explicitly passing in a timeout to customise the desired duration.

Types

type ActionCapability 

type ActionCapability interface {
	CallbackCapability
}

ActionCapability interface needs to be implemented by all action capabilities.

type BaseCapability 

type BaseCapability interface {
	Info(ctx context.Context) (CapabilityInfo, error)
}

BaseCapability interface needs to be implemented by all capability types. Capability interfaces are intentionally duplicated to allow for an easy change or extension in the future.

type CallbackCapability added in v0.2.0 

type CallbackCapability interface {
	BaseCapability
	CallbackExecutable
}

CallbackCapability is the interface implemented by action, consensus and target capabilities. This interface is useful when trying to capture capabilities of varying types.

type CallbackExecutable added in v0.2.0 

type CallbackExecutable interface {
	RegisterToWorkflow(ctx context.Context, request RegisterToWorkflowRequest) error
	UnregisterFromWorkflow(ctx context.Context, request UnregisterFromWorkflowRequest) error
	// Capability must respect context.Done and cleanup any request specific resources
	// when the context is cancelled. When a request has been completed the capability
	// is also expected to close the callback channel.
	// Request specific configuration is passed in via the request parameter.
	// A successful response must always return a value. An error is assumed otherwise.
	// The intent is to make the API explicit.
	Execute(ctx context.Context, request CapabilityRequest) (<-chan CapabilityResponse, error)
}

CallbackExecutable is an interface for executing a capability.

type CapabilityConfiguration 

type CapabilityConfiguration struct {
	DefaultConfig       *values.Map
	RemoteTriggerConfig *RemoteTriggerConfig
	RemoteTargetConfig  *RemoteTargetConfig
}

type CapabilityInfo 

type CapabilityInfo struct {
	// The capability ID is a fully qualified identifier for the capability.
	//
	// It takes the form of `{name}:{label1_key}_{labe1_value}:{label2_key}_{label2_value}@{version}`
	//
	// The labels within the ID are ordered alphanumerically.
	ID             string
	CapabilityType CapabilityType
	Description    string
	DON            *DON
	IsLocal        bool
}

CapabilityInfo is a struct for the info of a capability.

func MustNewCapabilityInfo 

func MustNewCapabilityInfo(
	id string,
	capabilityType CapabilityType,
	description string,
) CapabilityInfo

MustNewCapabilityInfo returns a new CapabilityInfo, `panic`ing if we could not instantiate a CapabilityInfo.

func MustNewRemoteCapabilityInfo 

func MustNewRemoteCapabilityInfo(
	id string,
	capabilityType CapabilityType,
	description string,
	don *DON,
) CapabilityInfo

MustNewRemoteCapabilityInfo returns a new CapabilityInfo, `panic`ing if we could not instantiate a CapabilityInfo.

func NewCapabilityInfo 

func NewCapabilityInfo(
	id string,
	capabilityType CapabilityType,
	description string,
) (CapabilityInfo, error)

NewCapabilityInfo returns a new CapabilityInfo.

func NewRemoteCapabilityInfo 

func NewRemoteCapabilityInfo(
	id string,
	capabilityType CapabilityType,
	description string,
	don *DON,
) (CapabilityInfo, error)

NewRemoteCapabilityInfo returns a new CapabilityInfo for remote capabilities. This is largely intended for internal use by the registry syncer. Capability developers should use `NewCapabilityInfo` instead as this omits the requirement to pass in the DON Info.

func (CapabilityInfo) Info 

func (c CapabilityInfo) Info(ctx context.Context) (CapabilityInfo, error)

Info returns the info of the capability.

func (CapabilityInfo) Version 

func (c CapabilityInfo) Version() string

Parse out the version from the ID.

type CapabilityRequest 

type CapabilityRequest struct {
	Metadata RequestMetadata
	Config   *values.Map
	Inputs   *values.Map
}

CapabilityRequest is a struct for the Execute request of a capability.

type CapabilityResponse 

type CapabilityResponse struct {
	Value *values.Map
	Err   error
}

CapabilityResponse is a struct for the Execute response of a capability.

type CapabilityType 

type CapabilityType string

CapabilityType is an enum for the type of capability. 

const (
	CapabilityTypeUnknown   CapabilityType = "unknown"
	CapabilityTypeTrigger   CapabilityType = "trigger"
	CapabilityTypeAction    CapabilityType = "action"
	CapabilityTypeConsensus CapabilityType = "consensus"
	CapabilityTypeTarget    CapabilityType = "target"
)

CapabilityType enum values.

func (CapabilityType) IsValid 

func (c CapabilityType) IsValid() error

IsValid checks if the capability type is valid.

type ConsensusCapability 

type ConsensusCapability interface {
	CallbackCapability
}

ConsensusCapability interface needs to be implemented by all consensus capabilities.

type DON 

type DON struct {
	ID               uint32
	ConfigVersion    uint32
	Members          []p2ptypes.PeerID
	F                uint8
	IsPublic         bool
	AcceptsWorkflows bool
}

DON represents a network of connected nodes.

For an example of an empty DON check, see the following link: https://github.com/goplugin/plugin_latest/blob/develop/core/capabilities/transmission/local_target_capability.go#L31

type Node 

type Node struct {
	PeerID         *p2ptypes.PeerID
	WorkflowDON    DON
	CapabilityDONs []DON
}

Node contains the node's peer ID and the DONs it is part of.

Note the following relationships between the workflow and capability DONs and this node.

There is a 1:0..1 relationship between this node and a workflow DON. This means that this node can be part at most one workflow DON at a time. As a side note, a workflow DON can have multiple nodes.

There is a 1:N relationship between this node and capability DONs, where N is the number of capability DONs. This means that this node can be part of multiple capability DONs at a time.

Although WorkflowDON is a value rather than a pointer, a node can be part of no workflow DON but 0 or more capability DONs. You can assert this by checking for zero values in the WorkflowDON field. See https://github.com/goplugin/plugin_latest/blob/develop/core/capabilities/transmission/local_target_capability.go#L31 for an example.

type RegisterToWorkflowRequest 

type RegisterToWorkflowRequest struct {
	Metadata RegistrationMetadata
	Config   *values.Map
}

type RegistrationMetadata 

type RegistrationMetadata struct {
	WorkflowID    string
	WorkflowOwner string
}

type RemoteTargetConfig 

type RemoteTargetConfig struct {
	RequestHashExcludedAttributes []string
}

type RemoteTriggerConfig 

type RemoteTriggerConfig struct {
	RegistrationRefresh     time.Duration
	RegistrationExpiry      time.Duration
	MinResponsesToAggregate uint32
	MessageExpiry           time.Duration
}

func (*RemoteTriggerConfig) ApplyDefaults 

func (c *RemoteTriggerConfig) ApplyDefaults()

NOTE: consider splitting this config into values stored in Registry (KS-118) and values defined locally by Capability owners.

type RequestMetadata 

type RequestMetadata struct {
	WorkflowID               string
	WorkflowOwner            string
	WorkflowExecutionID      string
	WorkflowName             string
	WorkflowDonID            uint32
	WorkflowDonConfigVersion uint32
	ReferenceID              string
}

type TargetCapability 

type TargetCapability interface {
	CallbackCapability
}

TargetsCapability interface needs to be implemented by all target capabilities.

type TriggerCapability 

type TriggerCapability interface {
	BaseCapability
	TriggerExecutable
}

TriggerCapability interface needs to be implemented by all trigger capabilities.

type TriggerEvent 

type TriggerEvent struct {
	TriggerType string
	ID          string
	Timestamp   string
	// Trigger-specific payload+metadata
	Metadata values.Value
	Payload  values.Value
}

type TriggerExecutable 

type TriggerExecutable interface {
	RegisterTrigger(ctx context.Context, request CapabilityRequest) (<-chan CapabilityResponse, error)
	UnregisterTrigger(ctx context.Context, request CapabilityRequest) error
}

type UnregisterFromWorkflowRequest 

type UnregisterFromWorkflowRequest struct {
	Metadata RegistrationMetadata
	Config   *values.Map
}

type Validatable 

type Validatable interface {
	// ValidateSchema returns the JSON schema for the capability.
	//
	// This schema includes the configuration, input and output schemas.
	Schema() (string, error)
}

type Validator 

type Validator[Config any, Inputs any, Outputs any] struct {
	ValidatorArgs
	// contains filtered or unexported fields
}

A Validator can validate the config, inputs, and outputs of a capability.

The library generates a JSON schema for each of these types to both describe the types in a language-agnostic way and to validate the API boundary of the capability.

To see how to annotate your structs with JSON schema tags, take a look at the jsonschema package.

func NewValidator 

func NewValidator[Config any, Inputs any, Outputs any](args ValidatorArgs) Validator[Config, Inputs, Outputs]

func (*Validator[Config, Inputs, Outputs]) ConfigSchema 

func (v *Validator[Config, Inputs, Outputs]) ConfigSchema() (string, error)

func (*Validator[Config, Inputs, Outputs]) InputsSchema 

func (v *Validator[Config, Inputs, Outputs]) InputsSchema() (string, error)

func (*Validator[Config, Inputs, Outputs]) OutputsSchema 

func (v *Validator[Config, Inputs, Outputs]) OutputsSchema() (string, error)

func (*Validator[Config, Inputs, Outputs]) Schema 

func (v *Validator[Config, Inputs, Outputs]) Schema() (string, error)

Schema returns the a JSON schema that combines the config, inputs, and outputs into a single schema.

This fully describes the capability's API boundary.

func (*Validator[Config, Inputs, Outputs]) ValidateConfig 

func (v *Validator[Config, Inputs, Outputs]) ValidateConfig(config *values.Map) (*Config, error)

func (*Validator[Config, Inputs, Outputs]) ValidateInputs 

func (v *Validator[Config, Inputs, Outputs]) ValidateInputs(inputs *values.Map) (*Inputs, error)

func (*Validator[Config, Inputs, Outputs]) ValidateOutputs 

func (v *Validator[Config, Inputs, Outputs]) ValidateOutputs(outputs *values.Map) (*Outputs, error)

type ValidatorArgs 

type ValidatorArgs struct {
	Info CapabilityInfo

	// You can customize each one of the reflectors
	// or leave them nil to use the default reflector.
	//
	// You can also override the default reflector by setting
	// the DefaultReflector field.
	DefaultReflector *jsonschema.Reflector

	SchemaReflector  *jsonschema.Reflector
	ConfigReflector  *jsonschema.Reflector
	InputsReflector  *jsonschema.Reflector
	OutputsReflector *jsonschema.Reflector
}

Source Files

View all Source files

Directories

Path Synopsis
consensus
ocr3
ocr3/datafeeds
ocr3/requests
ocr3/types
mocks

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.