plugin

README

Aethers Plugin Systems

We have based our plugin system off of hashicorps go-plugins. This was mainly so we could detach the need for matching dependencies. We use gRPC for communication

Example Plugin

There is an example plugin in the example directory with comments on the moving parts.

Install a Plugin

// TODO //

Create a Docker Image with your Plugin

// TODO //

Requirements for local setup

as we use gRPC and protobuffers, if you want to make changes to the .proto files you will need to install buf

go install github.com/bufbuild/buf/cmd/buf@v1.30.1
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.31.0

buf generate

Documentation

Index

• Variables
• type ExportPluginSystem
  • func (e *ExportPluginSystem) Load(ctx context.Context) error
• type Exporter
• type ExporterPlugin
  • func (p *ExporterPlugin) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)
  • func (p *ExporterPlugin) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error
• type GRPCClient
  • func (g *GRPCClient) Send(i *v1.Instance) error
• type GRPCServer
  • func (m *GRPCServer) Send(ctx context.Context, req *proto.InstanceRequest) (*proto.Empty, error)
• type PluginHandler
  • func NewHandler(ctx context.Context, e *ExportPluginSystem) *PluginHandler
  • func (p *PluginHandler) Handle(ctx context.Context, e *bus.Event)
  • func (p *PluginHandler) SendToExporters(ctx context.Context, e *bus.Event)
  • func (p *PluginHandler) Stop(ctx context.Context)
• type RegisteredPlugin
• type RegisteredSourcePlugin
• type SourceGRPCClient
  • func (g *SourceGRPCClient) Fetch(ctx context.Context) ([]*v1.Instance, error)
  • func (g *SourceGRPCClient) Stop(ctx context.Context) error
• type SourceGRPCServer
  • func (s *SourceGRPCServer) Fetch(ctx context.Context, p *proto.Empty) (*proto.ListInstanceResponse, error)
  • func (s *SourceGRPCServer) Stop(ctx context.Context, p *proto.Empty) (*proto.Empty, error)
• type SourcePlugin
  • func (s *SourcePlugin) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)
  • func (s *SourcePlugin) GRPCServer(broker *plugin.GRPCBroker, srv *grpc.Server) error
• type SourcePluginSystem
  • func (s *SourcePluginSystem) Load(ctx context.Context) error

Variables

var Handshake = plugin.HandshakeConfig{
	ProtocolVersion:  1,
	MagicCookieKey:   "AETHER_EXPORTER_PLUGIN",
	MagicCookieValue: "886c2a46-18b4-4090-8e13-0461439bb0d0",
}

Handshake is a common handshake that is shared by plugin and host. this is to make sure that versioning of plugins is equal and is not for security

var SourceHandshake = plugin.HandshakeConfig{
	ProtocolVersion:  1,
	MagicCookieKey:   "AETHER_SOURCE_PLUGIN",
	MagicCookieValue: "9cf50efe-f360-4c46-997f-e1ce7317adaf",
}

SourceHandshake is a common handshake that is shared by plugin and host. this is to make sure that versioning of plugins is equal and is not for security

Types

type ExportPluginSystem

type ExportPluginSystem struct {
	Dir string

	Plugins []*RegisteredPlugin
}

ExportPluginSystem is used to manage all third party exporters

func (*ExportPluginSystem) Load

func (e *ExportPluginSystem) Load(ctx context.Context) error

Load goes to a directory and runs every binary in that directory as a plugin The plugins for the exporter will need to adhere to the ExporterPlugin interface else they will fail to load

type Exporter

type Exporter interface {
	Send(i *v1.Instance) error
}

Exporter is the interface that plugins need to adhere to

type ExporterPlugin

type ExporterPlugin struct {
	// GRPCPlugin must still implement the Plugin interface
	plugin.Plugin
	// Concrete implementation, written in Go. This is only used for plugins
	// that are written in Go.
	Impl Exporter
}

This is the implementation of plugin.GRPCPlugin so we can serve/consume this.

func (*ExporterPlugin) GRPCClient

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

GRPCClient returns a gRPC client

func (*ExporterPlugin) GRPCServer

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

GRPCServer is used to setup a GRPC server

type GRPCClient

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

GRPCClient is an implementation of Exporter that can communicate over RPC

func (*GRPCClient) Send

func (g *GRPCClient) Send(i *v1.Instance) error

Send is used to fulfill the Exporter interface

type GRPCServer

type GRPCServer struct {
	Impl Exporter
}

GRPCServer is the gRPC server that GRPCClient talks to.

func (*GRPCServer) Send

func (m *GRPCServer) Send(
	ctx context.Context,
	req *proto.InstanceRequest,
) (*proto.Empty, error)

Send is used to receive the RPC requests

type PluginHandler

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

func NewHandler

func NewHandler(ctx context.Context, e *ExportPluginSystem) *PluginHandler

func (*PluginHandler) Handle

func (p *PluginHandler) Handle(ctx context.Context, e *bus.Event)

func (*PluginHandler) SendToExporters

func (p *PluginHandler) SendToExporters(ctx context.Context, e *bus.Event)

func (*PluginHandler) Stop

func (p *PluginHandler) Stop(ctx context.Context)

type RegisteredPlugin

type RegisteredPlugin struct {
	Name     string
	Exporter Exporter
	Client   plugin.ClientProtocol
}

RegisteredPlugin is all the information needed to manage a registered plugin

type RegisteredSourcePlugin

type RegisteredSourcePlugin struct {
	Name   string
	Source v1.Source
	Client plugin.ClientProtocol
}

RegisteredSourcePlugin is all the information needed to manage a registered plugin

type SourceGRPCClient

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

SourceGRPCClient is an implemntation of v1.Source that can communicate over RPC

func (*SourceGRPCClient) Fetch

func (g *SourceGRPCClient) Fetch(ctx context.Context) ([]*v1.Instance, error)

Fetch is used to fullfil the v1.Source interface over RPC

func (*SourceGRPCClient) Stop

func (g *SourceGRPCClient) Stop(ctx context.Context) error

Stop is used to fullfil the v1.Source interface over RPC

type SourceGRPCServer

type SourceGRPCServer struct {
	Impl v1.Source
}

SourceGRPCServer is an GRPC implementation over which SourceGRPClient communicates

func (*SourceGRPCServer) Fetch

func (s *SourceGRPCServer) Fetch(
	ctx context.Context,
	p *proto.Empty,
) (*proto.ListInstanceResponse, error)

Fetch is used to fulfill the GRPC Interface

func (*SourceGRPCServer) Stop

func (s *SourceGRPCServer) Stop(
	ctx context.Context,
	p *proto.Empty,
) (*proto.Empty, error)

Stop is used to fulfill the GRPC Interface

type SourcePlugin

type SourcePlugin struct {
	// GRPCPlugin must still implement the Plugin interface
	plugin.Plugin
	// Concrete implementation, written in Go. This is only used for plugins
	// that are written in Go.
	Impl v1.Source
}

SourcePlugin is the implementation of plugin.GRPCPlugin so we can cionsume this plugin

func (*SourcePlugin) GRPCClient

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

GRPCClient returns a gRPC client

func (*SourcePlugin) GRPCServer

func (s *SourcePlugin) GRPCServer(
	broker *plugin.GRPCBroker,
	srv *grpc.Server,
) error

GRPCServer is used to setup a GRPC server

type SourcePluginSystem

type SourcePluginSystem struct {
	Dir string

	Plugins []*RegisteredSourcePlugin
}

SourcePluginSystem is used to manage all third party source

func (*SourcePluginSystem) Load

func (s *SourcePluginSystem) Load(ctx context.Context) error

Load goes to a directory and runs every binary in that directory as a plugin The plugins for the sources will need to adhere to the SourcePlugin interface else they will fail to load