ldk

package module
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2020 License: MIT Imports: 12 Imported by: 1

README

Loop Development Kit (LDK) for Go

The LDK is a plugin system for Sidekick. The LDK is built with go-plugin, a HashiCorp plugin system used in several of their projects.

Plugins developed with this library are executed by Sidekick as separate processes. This ensures that crashes or instability in the plugin will not destabilize the Sidekick process.

Communication between Sidekick and the plugin is first initialized over stdio and then performed using GRPC. On mac and linux the GRPC communication is sent over unix domain socket and on windows over local TCP socket.

In order for Sidekick to use a plugin, it must be compiled. Sidekick does not compile or interpret source code at runtime. A consequence of this is that plugins will need to be compiled for each operating system that they want to support.

Installation

go get -u github.com/open-olive/loop-development-kit-go

Usage

Full documentation available on GoDoc.

Controllers

This LDK can be used to write controllers for Sidekick. More detail about controllers is available here.

Sensors

This LDK can be used to write sensors for Sidekick. More detail about sensors is available here.

Documentation

Index

Constants

View Source 
const (
	// CategoryUnknown is the category used when the category is not known
	CategoryUnknown = iota

	// CategoryIntelligence is the category used by intelligences
	CategoryIntelligence

	// CategoryController is the category used by controllers
	CategoryController

	// CategorySensor is the category used by sensors
	CategorySensor

	// CategorySidekick is the category used by the main sidekick process
	CategorySidekick
)

Variables

View Source 
var ControllerPluginMap = map[string]plugin.Plugin{
	"controller": &ControllerGRPCPlugin{},
}

ControllerPluginMap is the map of plugins we can dispense.

View Source 
var ErrUndocumentedStorageKey = errors.New("storage key is not present in documentation")

ErrUndocumentedStorageKey is the error returned if a plugin tries to access an undocumented storage key

View Source 
var Handshake = plugin.HandshakeConfig{
	ProtocolVersion:  1,
	MagicCookieKey:   "BASIC_PLUGIN",
	MagicCookieValue: "hello",
}

Handshake is a collection of information used to initialize communication between plugin and host

View Source 
var SensorPluginMap = map[string]plugin.Plugin{
	"sensor": &SensorGRPCPlugin{},
}

SensorPluginMap is the map of plugins we can dispense.

Functions

func ServeControllerPlugin added in v1.1.0 

func ServeControllerPlugin(logger *Logger, controller Controller)

ServeControllerPlugin serves a specific controller plugin.

func ServeSensorPlugin added in v1.1.0 

func ServeSensorPlugin(logger *Logger, sensor Sensor)

ServeSensorPlugin serves a specific sensor plugin.

Types

type Category 

type Category int

Category is a grouping of entity type

func (Category) MarshalJSON 

func (c Category) MarshalJSON() ([]byte, error)

MarshalJSON returns a json serialization of the category

func (Category) MarshalYAML 

func (c Category) MarshalYAML() (interface{}, error)

MarshalYAML returns a yaml serialization of the category

func (Category) String 

func (c Category) String() string

func (*Category) UnmarshalJSON 

func (c *Category) UnmarshalJSON(b []byte) error

UnmarshalJSON sets the category from the json data

func (*Category) UnmarshalYAML 

func (c *Category) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML sets the category from the yaml data

type Config 

type Config map[string]string

Config is a type used to store the configuration parameters of a plugin

type Controller 

type Controller interface {
	Start(ControllerHost) error
	Stop() error
	OnEvent(Event) error
}

Controller is an interface that defines the methods required of all controller plugins

type ControllerGRPCClient 

type ControllerGRPCClient struct {
	Metadata             Metadata
	StorageDocumentation *StorageDocumentation
	// contains filtered or unexported fields
}

ControllerGRPCClient is used by the controller plugin host to facilitate host initiated communication with controller plugins

func (*ControllerGRPCClient) OnEvent 

func (m *ControllerGRPCClient) OnEvent(event Event) error

OnEvent is called by the host to send an event to the controller

func (*ControllerGRPCClient) Start 

func (m *ControllerGRPCClient) Start(host ControllerHost) error

Start is called by the host when the plugin is started to provide access to the host process

func (*ControllerGRPCClient) Stop 

func (m *ControllerGRPCClient) Stop() error

Stop is called by the host when the plugin is stopped

type ControllerGRPCHostClient 

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

ControllerGRPCHostClient is used by the controller plugin to facilitate plugin initiated communication with the host

func (*ControllerGRPCHostClient) EmitWhisper 

func (m *ControllerGRPCHostClient) EmitWhisper(whisper Whisper) error

EmitWhisper is used by controller plugins to send whispers to sidekick

func (*ControllerGRPCHostClient) StorageDelete added in v1.1.0 

func (m *ControllerGRPCHostClient) StorageDelete(key string) error

StorageDelete is used by plugins to delete a storage entry

func (*ControllerGRPCHostClient) StorageDeleteAll added in v1.1.0 

func (m *ControllerGRPCHostClient) StorageDeleteAll() error

StorageDeleteAll is used by plugins to delete all storage entries

func (*ControllerGRPCHostClient) StorageHasKey added in v1.1.0 

func (m *ControllerGRPCHostClient) StorageHasKey(key string) (bool, error)

StorageHasKey is used by plugins to check if a key exists in storage

func (*ControllerGRPCHostClient) StorageKeys added in v1.1.0 

func (m *ControllerGRPCHostClient) StorageKeys() ([]string, error)

StorageKeys is used by plugins to get a list of keys for all entries

func (*ControllerGRPCHostClient) StorageRead added in v1.1.0 

func (m *ControllerGRPCHostClient) StorageRead(key string) (string, error)

StorageRead is used by plugins to get the value of an entry

func (*ControllerGRPCHostClient) StorageReadAll added in v1.1.0 

func (m *ControllerGRPCHostClient) StorageReadAll() (map[string]string, error)

StorageReadAll is used by plugins to get a map of all entries

func (*ControllerGRPCHostClient) StorageWrite added in v1.1.0 

func (m *ControllerGRPCHostClient) StorageWrite(key, value string) error

StorageWrite is used by plugins to set an entry

type ControllerGRPCHostServer 

type ControllerGRPCHostServer struct {
	// This is the real implementation
	Impl ControllerHost

	Metadata             Metadata
	StorageDocumentation *StorageDocumentation
}

ControllerGRPCHostServer is used by the controller plugin host to receive plugin initiated communication

func (*ControllerGRPCHostServer) EmitWhisper 

func (m *ControllerGRPCHostServer) EmitWhisper(ctx context.Context, req *proto.EmitWhisperRequest) (*proto.Empty, error)

EmitWhisper is used by controller plugins to send whispers to sidekick

func (*ControllerGRPCHostServer) StorageDelete added in v1.1.0 

func (m *ControllerGRPCHostServer) StorageDelete(ctx context.Context, req *proto.StorageDeleteRequest) (*proto.Empty, error)

StorageDelete is used by plugins to delete a storage entry

func (*ControllerGRPCHostServer) StorageDeleteAll added in v1.1.0 

func (m *ControllerGRPCHostServer) StorageDeleteAll(ctx context.Context, req *proto.Empty) (*proto.Empty, error)

StorageDeleteAll is used by plugins to delete all storage entries

func (*ControllerGRPCHostServer) StorageHasKey added in v1.1.0 

func (m *ControllerGRPCHostServer) StorageHasKey(ctx context.Context, req *proto.StorageHasKeyRequest) (*proto.StorageHasKeyResponse, error)

StorageHasKey is used by plugins to check if a key exists in storage

func (*ControllerGRPCHostServer) StorageKeys added in v1.1.0 

func (m *ControllerGRPCHostServer) StorageKeys(ctx context.Context, req *proto.Empty) (*proto.StorageKeysResponse, error)

StorageKeys is used by plugins to get a list of keys for all entries

func (*ControllerGRPCHostServer) StorageRead added in v1.1.0 

func (m *ControllerGRPCHostServer) StorageRead(ctx context.Context, req *proto.StorageReadRequest) (*proto.StorageReadResponse, error)

StorageRead is used by plugins to get the value of an entry

func (*ControllerGRPCHostServer) StorageReadAll added in v1.1.0 

func (m *ControllerGRPCHostServer) StorageReadAll(ctx context.Context, req *proto.Empty) (*proto.StorageReadAllResponse, error)

StorageReadAll is used by plugins to get a map of all entries

func (*ControllerGRPCHostServer) StorageWrite added in v1.1.0 

func (m *ControllerGRPCHostServer) StorageWrite(ctx context.Context, req *proto.StorageWriteRequest) (*proto.Empty, error)

StorageWrite is used by plugins to set an entry

type ControllerGRPCPlugin added in v1.1.0 

type ControllerGRPCPlugin struct {
	plugin.NetRPCUnsupportedPlugin
	Impl Controller
}

ControllerGRPCPlugin is a structure used to define the parameters of the plugin communication

func (*ControllerGRPCPlugin) GRPCClient added in v1.1.0 

func (p *ControllerGRPCPlugin) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

GRPCClient is used to generate controller clients that can be used by the host

func (*ControllerGRPCPlugin) GRPCServer added in v1.1.0 

func (p *ControllerGRPCPlugin) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

GRPCServer is used to register the controller plugin with the GRPC server

type ControllerGRPCServer 

type ControllerGRPCServer struct {
	Impl Controller
	// contains filtered or unexported fields
}

ControllerGRPCServer is used by the controller plugin to receive host initiated communication

func (*ControllerGRPCServer) OnEvent 

func (m *ControllerGRPCServer) OnEvent(ctx context.Context, req *proto.OnEventRequest) (*proto.Empty, error)

OnEvent is called by the host to send an event to the plugin

func (*ControllerGRPCServer) Start 

func (m *ControllerGRPCServer) Start(ctx context.Context, req *proto.StartRequest) (*proto.Empty, error)

Start is called by the host when the plugin is started to provide access to the host process

func (*ControllerGRPCServer) Stop 

func (m *ControllerGRPCServer) Stop(ctx context.Context, req *proto.Empty) (*proto.Empty, error)

Stop is called by the host when the plugin is stopped

type ControllerHost 

type ControllerHost interface {
	EmitWhisper(Whisper) error
	StorageDelete(string) error
	StorageDeleteAll() error
	StorageHasKey(string) (bool, error)
	StorageKeys() ([]string, error)
	StorageRead(string) (string, error)
	StorageReadAll() (map[string]string, error)
	StorageWrite(string, string) error
}

ControllerHost is an interface that defines what methods plugins can expect from the host

type Event 

type Event struct {
	Source Source            `json:"source"`
	Data   map[string]string `json:"data"`
}

Event is a structure that defines a sensor event

func NewTextEvent 

func NewTextEvent(text string) Event

NewTextEvent generates a new event with the given text

func (*Event) Text 

func (e *Event) Text() string

Text is a shortcut for returning Event.Data["text"]

type Logger added in v1.1.0 

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

Logger is a logger implementation, which wraps an hclog Logger.

func NewLogger added in v1.1.0 

func NewLogger(name string) *Logger

NewLogger returns a configured logger.

func (*Logger) Debug added in v1.1.0 

func (l *Logger) Debug(msg string, args ...interface{})

Debug emits the message and args at DEBUG level.

func (*Logger) Error added in v1.1.0 

func (l *Logger) Error(msg string, args ...interface{})

Error emits the message and args at ERROR level.

func (*Logger) Info added in v1.1.0 

func (l *Logger) Info(msg string, args ...interface{})

Info emits the message and args at INFO level.

func (*Logger) Logger added in v1.1.0 

func (l *Logger) Logger() hclog.Logger

Logger returns the underlying logger.

func (*Logger) Trace added in v1.1.0 

func (l *Logger) Trace(msg string, args ...interface{})

Trace emits the message and args at TRACE level.

func (*Logger) Warn added in v1.1.0 

func (l *Logger) Warn(msg string, args ...interface{})

Warn emits the message and args at WARN level.

func (*Logger) With added in v1.1.0 

func (l *Logger) With(args ...interface{}) *Logger

With creates a sublogger that will always have the given key/value pairs.

type Metadata 

type Metadata struct {
	// Author is the creator of the entity
	Author string `json:"author" yaml:"author"`

	// Category is a grouping of entity type
	// Ex: "intelligence", "loop", "sensor"
	Category Category `json:"category" yaml:"category"`

	// Created is the time when the entity was created
	Created time.Time `json:"created" yaml:"created"`

	// Description is a short explanation of the entity
	Description string `json:"description" yaml:"description"`

	// Entrypoint is the path to the binary or the command (relative to the working directory)
	// to run on plugin start (defaults to "plugin"/"plugin.exe")
	Entrypoint []string `json:"entrypoint" yaml:"executable"`

	// ID is a unique identifier for this entity
	ID string `json:"id" yaml:"id"`

	// Icon is a URL for an icon representing this entity
	Icon string `json:"icon" yaml:"icon"`

	// Name is a human readable identifier for this entity
	Name string `json:"name" yaml:"name"`

	// Organization is the name of the organization to which the Author belongs
	Organization string `json:"organization" yaml:"organization"`

	// Specification is a string indication which version
	// of the specification is being used to describe this entity
	Specification string `json:"specification" yaml:"specification"`

	// Updated is the time when the entity was last updated
	Updated time.Time `json:"updated" yaml:"updated"`

	// Version is a semver version of this entity
	Version string `json:"version" yaml:"version"`
}

Metadata is data about an entity

type Sensor 

type Sensor interface {
	Start(SensorHost) error
	Stop() error
	OnEvent(Event) error
}

Sensor is an interface that defines the methods required of all sensor plugins

type SensorGRPCClient 

type SensorGRPCClient struct {
	Metadata             Metadata
	StorageDocumentation *StorageDocumentation
	// contains filtered or unexported fields
}

SensorGRPCClient is used by the sensor plugin host to facilitate host initiated communication with sensor plugins

func (*SensorGRPCClient) OnEvent 

func (m *SensorGRPCClient) OnEvent(event Event) error

OnEvent is called by the host to send an event to the sensor

func (*SensorGRPCClient) Start 

func (m *SensorGRPCClient) Start(host SensorHost) error

Start is called by the host when the plugin is started to provide access to the host process

func (*SensorGRPCClient) Stop 

func (m *SensorGRPCClient) Stop() error

Stop is called by the host when the plugin is stopped

type SensorGRPCHostClient 

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

SensorGRPCHostClient is used by the sensor plugin to facilitate plugin initiated communication with the host

func (*SensorGRPCHostClient) EmitEvent 

func (m *SensorGRPCHostClient) EmitEvent(event Event) error

EmitEvent is used by sensor plugins to send events to the host

func (*SensorGRPCHostClient) StorageDelete added in v1.1.0 

func (m *SensorGRPCHostClient) StorageDelete(key string) error

StorageDelete is used by plugins to delete a storage entry

func (*SensorGRPCHostClient) StorageDeleteAll added in v1.1.0 

func (m *SensorGRPCHostClient) StorageDeleteAll() error

StorageDeleteAll is used by plugins to delete all storage entries

func (*SensorGRPCHostClient) StorageHasKey added in v1.1.0 

func (m *SensorGRPCHostClient) StorageHasKey(key string) (bool, error)

StorageHasKey is used by plugins to check if a key exists in storage

func (*SensorGRPCHostClient) StorageKeys added in v1.1.0 

func (m *SensorGRPCHostClient) StorageKeys() ([]string, error)

StorageKeys is used by plugins to get a list of keys for all entries

func (*SensorGRPCHostClient) StorageRead added in v1.1.0 

func (m *SensorGRPCHostClient) StorageRead(key string) (string, error)

StorageRead is used by plugins to get the value of an entry

func (*SensorGRPCHostClient) StorageReadAll added in v1.1.0 

func (m *SensorGRPCHostClient) StorageReadAll() (map[string]string, error)

StorageReadAll is used by plugins to get a map of all entries

func (*SensorGRPCHostClient) StorageWrite added in v1.1.0 

func (m *SensorGRPCHostClient) StorageWrite(key, value string) error

StorageWrite is used by plugins to set an entry

type SensorGRPCHostServer 

type SensorGRPCHostServer struct {
	// This is the real implementation
	Impl SensorHost

	Metadata             Metadata
	StorageDocumentation *StorageDocumentation
}

SensorGRPCHostServer is used by the sensor plugin host to receive plugin initiated communication

func (*SensorGRPCHostServer) EmitEvent 

func (m *SensorGRPCHostServer) EmitEvent(ctx context.Context, req *proto.EmitEventRequest) (*proto.Empty, error)

EmitEvent is used by sensor plugins to send events to the host

func (*SensorGRPCHostServer) StorageDelete added in v1.1.0 

func (m *SensorGRPCHostServer) StorageDelete(ctx context.Context, req *proto.StorageDeleteRequest) (*proto.Empty, error)

StorageDelete is used by plugins to delete a storage entry

func (*SensorGRPCHostServer) StorageDeleteAll added in v1.1.0 

func (m *SensorGRPCHostServer) StorageDeleteAll(ctx context.Context, req *proto.Empty) (*proto.Empty, error)

StorageDeleteAll is used by plugins to delete all storage entries

func (*SensorGRPCHostServer) StorageHasKey added in v1.1.0 

func (m *SensorGRPCHostServer) StorageHasKey(ctx context.Context, req *proto.StorageHasKeyRequest) (*proto.StorageHasKeyResponse, error)

StorageHasKey is used by plugins to check if a key exists in storage

func (*SensorGRPCHostServer) StorageKeys added in v1.1.0 

func (m *SensorGRPCHostServer) StorageKeys(ctx context.Context, req *proto.Empty) (*proto.StorageKeysResponse, error)

StorageKeys is used by plugins to get a list of keys for all entries

func (*SensorGRPCHostServer) StorageRead added in v1.1.0 

func (m *SensorGRPCHostServer) StorageRead(ctx context.Context, req *proto.StorageReadRequest) (*proto.StorageReadResponse, error)

StorageRead is used by plugins to get the value of an entry

func (*SensorGRPCHostServer) StorageReadAll added in v1.1.0 

func (m *SensorGRPCHostServer) StorageReadAll(ctx context.Context, req *proto.Empty) (*proto.StorageReadAllResponse, error)

StorageReadAll is used by plugins to get a map of all entries

func (*SensorGRPCHostServer) StorageWrite added in v1.1.0 

func (m *SensorGRPCHostServer) StorageWrite(ctx context.Context, req *proto.StorageWriteRequest) (*proto.Empty, error)

StorageWrite is used by plugins to set an entry

type SensorGRPCPlugin added in v1.1.0 

type SensorGRPCPlugin struct {
	plugin.NetRPCUnsupportedPlugin
	Impl Sensor
}

SensorGRPCPlugin is a structure used to define the parameters of the plugin communication

func (*SensorGRPCPlugin) GRPCClient added in v1.1.0 

func (p *SensorGRPCPlugin) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

GRPCClient is used to generate sensor clients that can be used by the host

func (*SensorGRPCPlugin) GRPCServer added in v1.1.0 

func (p *SensorGRPCPlugin) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

GRPCServer is used to register the sensor plugin with the GRPC server

type SensorGRPCServer 

type SensorGRPCServer struct {
	Impl Sensor
	// contains filtered or unexported fields
}

SensorGRPCServer is used by the sensor plugin to receive host initiated communication

func (*SensorGRPCServer) OnEvent 

func (m *SensorGRPCServer) OnEvent(ctx context.Context, req *proto.OnEventRequest) (*proto.Empty, error)

OnEvent is called by the host to send an event to the plugin

func (*SensorGRPCServer) Start 

func (m *SensorGRPCServer) Start(ctx context.Context, req *proto.StartRequest) (*proto.Empty, error)

Start is called by the host when the plugin is started to provide access to the host process

func (*SensorGRPCServer) Stop 

func (m *SensorGRPCServer) Stop(ctx context.Context, req *proto.Empty) (*proto.Empty, error)

Stop is called by the host when the plugin is stopped

type SensorHost 

type SensorHost interface {
	EmitEvent(Event) error
	StorageDelete(string) error
	StorageDeleteAll() error
	StorageHasKey(string) (bool, error)
	StorageKeys() ([]string, error)
	StorageRead(string) (string, error)
	StorageReadAll() (map[string]string, error)
	StorageWrite(string, string) error
}

SensorHost is an interface that defines what methods plugins can expect from the host

type Source 

type Source struct {
	// Author is the creator of the entity
	Author string `json:"author" yaml:"author"`

	// Category is a grouping of entity type
	// Ex: "intelligence", "loop", "sensor"
	Category Category `json:"category" yaml:"category"`

	// ID is a unique identifier for this entity
	ID string `json:"id" yaml:"id"`

	// Name is a human readable identifier for this entity
	Name string `json:"name" yaml:"name"`

	// Organization is the name of the organization to which the Author belongs
	Organization string `json:"organization" yaml:"organization"`

	// Version is a semver version of this entity
	Version string `json:"version" yaml:"version"`
}

Source is information about the origin of the data

type StorageDocumentation added in v1.1.0 

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

StorageDocumentation is a struct containing storage documentation

func (*StorageDocumentation) Entries added in v1.1.0 

func (s *StorageDocumentation) Entries() map[string]StorageDocumentationEntry

Entries returns a map of StorageDocumentationEntrys

func (*StorageDocumentation) HasKey added in v1.1.0 

func (s *StorageDocumentation) HasKey(key string) bool

HasKey returns true if the provided key is present in the documentation

func (*StorageDocumentation) Keys added in v1.1.0 

func (s *StorageDocumentation) Keys() []string

Keys returns a slice of all the keys in the documentation

func (*StorageDocumentation) UnmarshalJSON added in v1.1.0 

func (s *StorageDocumentation) UnmarshalJSON(data []byte) error

UnmarshalJSON populates the entries of the documentation from bytes of json

type StorageDocumentationEntry added in v1.1.0 

type StorageDocumentationEntry struct {
	Description string `json:"description" yaml:"description"`
	Name        string `json:"name" yaml:"name"`
	Secure      bool   `json:"secure" yaml:"secure"`
}

StorageDocumentationEntry contains the information about a single element in the storage documentation

type Style 

type Style struct {
	BackgroundColor string `json:"backgroundColor"`
	HighlightColor  string `json:"highlightColor"`
	PrimaryColor    string `json:"primaryColor"`
}

Style contains fields for specifying whisper style

type Whisper 

type Whisper struct {
	Markdown  string    `json:"markdown"`
	CreatedAt time.Time `json:"createdAt"`
	ID        string    `json:"id"`
	Icon      string    `json:"icon"` // Material Icon name https://material.io/resources/icons/
	Label     string    `json:"label"`
	Style     Style     `json:"style"`
	Source    Source    `json:"source"`
}

Whisper is the information output of a loop

func NewWhisper 

func NewWhisper(markdown string, label string, icon string, style Style) (Whisper, error)

NewWhisper creates a new Whisper struct with a random ID

Source Files

View all Source files

Directories

Path Synopsis

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.