ldk

package module
v1.3.1 Latest Latest
Warning

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

 Go to latest Published: Sep 17, 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.

Development

protoc

The LDK utilizes protoc to create the protobuf that defines the contract that is utilized by GRPC.

  • Install protobuf with Homebrew brew link protobuf
  • Make your changes to proto/ldk.proto
  • Then generate the new protobuf file with make proto/ldk.pb.go

Since proto/ldk.pb.go is auto-generated, do not edit this file directly.

Running Locally

Sidekick lets you add a local command as Local Plugins:

  1. Open Sidekick.
  2. Open the Loop Library:
    1. Click the Hamburger icon.
    2. Click Loop Library.
  3. Click the Install Local Plugin button:
  4. Select whether it's a Controller or Sensor.
  5. Select the working directory for the command.
  6. Enter the command to be executed, including any arguments.
  7. Click Install.

The command will be installed as a plugin. If you need to change the command or its arguments you'll need remove it and then add the new commands. If you are developing locally, it can be helpful to give it the go run command, as this will remove the need to recompile each time to check your changes:

go run main.go

Be sure that when you selected the Directory in Step 5 that it is the root of your project that has the main.go file located in it.

Troubleshooting and Debugging

Sidekick logs are available in the following directories for your OS:

~/Library/Logs/Sidekick  # MacOS
/var/log/Sidekick        # Linux
%AppData%\Sidekick\Logs\ # Windows
Tailing Logs

It can be useful to tail the log as you develop to see any errors, warnings, or info messages. To do so, you can issue any of the following commands:

Linux
tail -f /var/log/Sidekick/Sidekick-2020.08.12-1dcc37a.log
Mac
tail -f ~/Library/Logs/Sidekick/Sidekick-2020.08.12-1dcc37a.log
Windows

From Powershell (not a cmd shell):

Get-Content $env:AppData\Sidekick\Logs\Sidekick-2020.08.12-1dcc37a.log –Wait

Note: File names may differ from the example above.

Configuration
storage.json

Each storage key you access must be specified in the storage.json file.

{
  "storage-key": {
    "name": "Storage Key Name",
    "description": "What you're containing in this key"
  },
  "storage-key2": {
    "name": "Storage Key 2",
    "description": "What you're containing in this key"
  }
}

Documentation

Overview

This package is an LDK (loop development kit) for plugins for the Sidekick project.

The LDK is built with go-plugin (https://github.com/hashicorp/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 (https://grpc.io/). 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.

Controllers

Controllers receive events and use them to generate relevant whispers. Controllers choose which events they want to use and which they want to ignore.

Controller Interface

Writing a Controller plugin boils down to writing an implementation for the Controller interface. 

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

Start() - The Controller should wait to start operating until this is called. The provided `ControllerHost` should be stored in memory for continued use.

Stop() - The Controller should stop operating when this is called.

OnEvent() - The controller can use this to handle events that are broadcast by Sensors. Controllers do not need to emit events in a 1:1 relationship with events. Controllers may not use events at all. Controllers may only use some events. Controllers may keep a history of events and only emit whispers when several conditions are met.

Controller Lifecycle

1. Sidekick executes plugin process

2. Sidekick calls `Start`, sending the host connection information to the plugin. This connection information is used to create the `ControllerHost`. The `ControllerHost` interface allows the plugin to emit whispers.

3. On Controller wanting to emit a whisper, the Controller calls the `EmitWhisper` method on the host interface.

4. On Sensor event, Sidekick calls `OnEvent`, passing the event from the Sensor to the Controller. These events can be ignored or used at the Controller's choice.

5. On User disabling the Controller, Sidekick calls `Stop` then sends `sigterm` to the process.

6. On Sidekick shutdown, Sidekick calls `Stop` then sends `sigterm` to the process.*

Basic Controller Example

We recommend using this repo as a starting point when creating a new controller: https://github.com/open-olive/sidekick-controller-examplego

Sensors

A Sensor is a type of plugin that generates events. Events can be as simple as a chunk of text but allow for complicated information. Sensors do not choose which controllers get their events. They are simply emitting the events. The decision about which events to use is left to the controller.

Sensor Interface

Writing a Sensor plugin boils down to writing an implementation for the Sensor interface. 

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

Start() - The Sensor should wait to start operating until this is called. The provided `SensorHost` should be stored in memory for continued use.

Stop() - The Sensor should stop operating when this is called.

OnEvent() - The sensor can use this to handle events from the Sidekick UI. Many sensors will not care about UI events, and in that case the function should just return `nil`.

Sensor Lifecycle

1. Sidekick executes plugin process

2. Sidekick calls `Start`, sending the host connection information to the plugin. This connection information is used to create the `SensorHost`. The `SensorHost` interface allows the plugin to emit events.

3. On Sensor wanting to emit an event, the Sensor calls the `EmitEvent` method on the host interface.

4. On Sidekick UI event, Sidekick calls `OnEvent`, passing the event to the Sensor. These events can be ignore or used at the Sensor's choice.

5. On User disabling the Sensor, Sidekick calls `Stop` then sends `sigterm` to the process.

6. On Sidekick shutdown, Sidekick calls `Stop` then sends `sigterm` to the process.

Index

Constants

This section is empty.

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 Access added in v1.2.0 

type Access string

Access is a grouping of entity type 

const (
	// AccessUnknown is the access value used when the value is not known
	AccessUnknown Access = "unknown"

	// AccessUser is the value that allows only the user who submitted the plugin to access it
	AccessUser Access = "user"

	// AccessOrganization is the value that allows only users in the submitting user's organization to access the plugin
	AccessOrganization Access = "organization"

	// AccessPublic is the value that allows any user of Sidekick to access the plugin
	AccessPublic Access = "public"
)

type Category 

type Category int

Category is a grouping of entity type 

const (
	// CategoryUnknown is the category used when the category is not known
	CategoryUnknown Category = 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
)

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) (string, 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

func (*ControllerGRPCHostClient) UpdateWhisper added in v1.3.0 

func (m *ControllerGRPCHostClient) UpdateWhisper(whisper Whisper, id string) error

UpdateWhisper is used by controller plugins to update whispers already sent to sidekick

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.EmitWhisperResponse, 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

func (*ControllerGRPCHostServer) UpdateWhisper added in v1.3.0 

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

UpdateWhisper is used by controller plugins to update whispers already sent to sidekick

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) (string, 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
	UpdateWhisper(Whisper, string) error
}

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

type Event 

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

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: "Category", "Intelligence", "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:"entrypoint"`

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

	// ID is a unique identifier for this entity that is consistent across all versions
	// and modifications of 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"`

	// 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"`

	// UploadID is the unique upload identifier for this entity that is specific to this
	// exact version of this entity. Unlike the ID, the UploadID will change with every
	// version and between operating systems.
	UploadID string `json:"uploadId" yaml:"uploadId"`

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

Metadata is data about an entity.

type OperatingSystem added in v1.2.0 

type OperatingSystem string

OperatingSystem is a grouping of entity type 

const (
	// OperatingSystemUnknown is the OS value used when the OS is not known
	OperatingSystemUnknown OperatingSystem = "unknown"

	// OperatingSystemWindows is the OS value used for Windows
	OperatingSystemWindows OperatingSystem = "win32"

	// OperatingSystemMacOS is the OS value used for MacOS
	OperatingSystemMacOS OperatingSystem = "darwin"

	// OperatingSystemLinux is the OS value used for Linux
	OperatingSystemLinux OperatingSystem = "linux"

	// OperatingSystemAny is the OS value used a plugin is available on any OS
	OperatingSystemAny OperatingSystem = "any"
)

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: "Category", "Intelligence", "Sensor"
	Category Category `json:"category" yaml:"category"`

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

	// ID is a unique identifier for this entity that is consistent across all versions
	// and modifications of 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"`

	// UploadID is the unique upload identifier for this entity that is specific to this
	// exact version of this entity. Unlike the ID, the UploadID will change with every
	// version and between operating systems.
	UploadID string `json:"uploadId" yaml:"uploadId"`

	// 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 {
	CreatedAt time.Time `json:"createdAt"`
	Icon      string    `json:"icon"` // Material Icon name https://material.io/resources/icons/
	ID        string    `json:"id"`
	Label     string    `json:"label"`
	Markdown  string    `json:"markdown"`
	Source    Source    `json:"source"`
	Style     Style     `json:"style"`
}

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.