goplugin

README

quadroops/goplugin

This package is a library to implement modular and pluggable architecture for application using Golang's language.

This library inspired from hashicorp's plugin architecture, but just to implement it in different ways, such as:

1. Using single file configuration to explore all available plugins (customizable)
2. Adding REST as an alternatives of communication protocols

We have a same direction with hashicorp's plugin:

1. Using subprocess
2. Supported multiple languages (as long as support with GRPC/REST)

Why we doesn't support golang's native plugin ? It's because using Symbol for exported variable and methods, it's easy for simple plugin but it will harder to maintain for complex application

---

Flows

// need a way to discover available plugins
[host] -----<discover>---> [plugin]


// start subprocess, should be sharing a same PID
[host] ------<exec>-----> [plugin]


// communicate via REST or GRPC 
[host] ---<communicate>------> [plugin]

We have three main flows:

• Discover
• Exec
• Communication via rpc

Current supported communication protocols:

• REST
• GRPC

---

Usages

Basic usages:

// need to save plugin's configuration ports
// assume this plugin using rest
hostAPlugin1Conf := goplugin.PluginConf{
	Protocol: &goplugin.ProtocolOption{
		RESTOpts: &driver.RESTOptions{
			Addr: "localhost",
			Port: 8080,
			Timeout: 10, // in seconds
		}
	}
}

// assume this plugin using grpc
hostAPlugin2Conf := goplugin.PluginConf{
	Protocol: &goplugin.ProtocolOption{
		GRPCOpts: &driver.GRPCOptions{
			Addr: "host",
			Port: 8081,
		}
	}
}

// each hosts will have to manage their own plugin's configurations
// we need to map available plugins to their specific configurations
hostA := goplugin.New("hostA").SetupPlugin(
	goplugin.Map("plugin1", hostAPlugin1PConf), 
	goplugin.Map("plugin2", hostAPlugin2Conf),
)

// you can register multiple hosts here
// and whel Install method called, it will install all plugins from
// all registered hosts
pluggable, err := goplugin.Register(hostA).Install()
if err != nil {
	panic(err)
}

defer func() {
	// for each successfull installed hosts need to shutdown
	// their plugins if something bad happened
	pluggable.KillPlugins()
}

// when load a plugin, you need to specify from which host
// each host will have their own plugin registries
// if plugin not started yet, it should also run plugin via os subprocess
plugin1, err := pluggable.Get("hostA", "plugin1")
if err != nil {
	panic(err)
}

// start working with available plugins
respPing, err := plugin1.Ping()
if err != nil {
	panic(err)
}

log.Printf("Response ping: %s", respPing)

Assume you need to customize config Checker and Parser, imagine you want to using a database like Mongodb as configuration source.

// implement discover.Checker
func Check() string {
    return 'mongodb://localhost:27017/dbname'
}

// implement discover.SourceReader
func MongoSourceReader(source string) ([]byte, error) {
    // parse configurations from mongodb
}

// implement discover.Parser
func MongoParse(content []byte) (*discover.PluginConfig, error) {
    // map configurations to discover.PluginConfig
}

// need to save plugin's configuration ports
// assume this plugin using rest
hostAPlugin1Conf := goplugin.PluginConf{
	Protocol: &goplugin.ProtocolOption{
		RESTOpts: &driver.RESTOptions{
			Addr: "localhost",
			Port: 8080,
			Timeout: 10, // in seconds
		}
	}
}

hostA := goplugin.New("hostA", 
    goplugin.WithCustomConfigChecker(Check), 
    goplugin.WithCustomConfigParser(MongoSourceReader, MongoParse),
).SetupPlugin(goplugin.Map("plugin1", hostAPlugin1PConf))

// you can register multiple hosts here
// and whel Install method called, it will install all plugins from
// all registered hosts
pluggable, err := goplugin.Register(hostA).Install()
if err != nil {
	panic(err)
}

defer func() {
	// for each successfull installed hosts need to shutdown
	// their plugins if something bad happened
	pluggable.KillPlugins()
}

// when load a plugin, you need to specify from which host
// each host will have their own plugin registries
// if plugin not started yet, it should also run plugin via os subprocess
plugin1, err := pluggable.Get("hostA", "plugin1")
if err != nil {
	panic(err)
}

// start working with available plugins
respPing, err := plugin1.Ping()
if err != nil {
	panic(err)
}

log.Printf("Response ping: %s", respPing)

Customizated components available for:

• ConfigChecker (default: get toml file path)
• ConfigParser (default: toml parser)
• ProcessInstance (default: subprocess)
• HostIdentityChecker (default: MD5Checker)

Available options for customization:

• goplugin.WithCustomConfigChecker
• goplugin.WithCustomConfigParser
• goplugin.WithCustomIdentityChecker
• goplugin.WithCustomProcess

---

Examples

Please refer to our examples

Documentation

Index

• func BuildProtocol(opt *ProtocolOption) caller.Builder
• type GoPlugin
  • func New(hostName string, opts ...Option) *GoPlugin
  • func (g *GoPlugin) Build() (*host.Builder, error)
  • func (g *GoPlugin) GetPluginConf(pluginName string) (*PluginConf, error)
  • func (g *GoPlugin) GetProcessInstance() *process.Instance
  • func (g *GoPlugin) SetupPlugin(plugins ...PluginMapper) *GoPlugin
• type Option
  • func WithCustomConfigChecker(adapters ...discover.Checker) Option
  • func WithCustomConfigParser(parserAdapter discover.Parser, sourceAdapter discover.SourceReader) Option
  • func WithCustomIdentityChecker(adapter host.IdentityChecker) Option
  • func WithCustomProcess(runner process.Runner, processes process.ProcessesBuilder) Option
• type PluginConf
• type PluginMapper
  • func Map(pluginName string, conf *PluginConf) PluginMapper
• type ProtocolOption
• type Registry
  • func Register(hostPlugins ...*GoPlugin) *Registry
  • func (r *Registry) Get(host, plugin string) (*caller.Plugin, error)
  • func (r *Registry) Install() (*Registry, error)
  • func (r *Registry) KillPlugins()

Functions

func BuildProtocol

func BuildProtocol(opt *ProtocolOption) caller.Builder

BuildProtocol a helper to check and also generate a default protocol should be used like a REST or GRPC

Types

type GoPlugin

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

GoPlugin used as main struct to store goplugin's state

func New

func New(hostName string, opts ...Option) *GoPlugin

New used to create new instance of GoPlugin, you can provide customization here by giving goplugin.Option

func (*GoPlugin) Build

func (g *GoPlugin) Build() (*host.Builder, error)

Build used to compile current host instance into consumed state of host.Builder

func (*GoPlugin) GetPluginConf

func (g *GoPlugin) GetPluginConf(pluginName string) (*PluginConf, error)

GetPluginConf used to get plugin's config

func (*GoPlugin) GetProcessInstance

func (g *GoPlugin) GetProcessInstance() *process.Instance

GetProcessInstance .

func (*GoPlugin) SetupPlugin

func (g *GoPlugin) SetupPlugin(plugins ...PluginMapper) *GoPlugin

SetupPlugin used to store host plugin's configurations

type Option

type Option func(*GoPlugin)

Option used to customize default objects

func WithCustomConfigChecker

func WithCustomConfigChecker(adapters ...discover.Checker) Option

WithCustomConfigChecker used to customize config checker, the parameter must be implement discover.Checker

func WithCustomConfigParser

func WithCustomConfigParser(parserAdapter discover.Parser, sourceAdapter discover.SourceReader) Option

WithCustomConfigParser used to customize config reader & parser, given adapters must be implement discover.Parser and discover.SourceReader interfaces

func WithCustomIdentityChecker

func WithCustomIdentityChecker(adapter host.IdentityChecker) Option

WithCustomIdentityChecker used to customize plugin's identity checker, given adapter must implement host.IdentityChecker

func WithCustomProcess

func WithCustomProcess(runner process.Runner, processes process.ProcessesBuilder) Option

WithCustomProcess used to customize process runner and process data builder (including registry)

type PluginConf

type PluginConf struct {
	Protocol *ProtocolOption
}

PluginConf used to store plugin's configurations

type PluginMapper

type PluginMapper map[string]*PluginConf

PluginMapper used as registry to store plugin's config

func Map

func Map(pluginName string, conf *PluginConf) PluginMapper

Map used to put a plugin and assign it with their spesific configurations

type ProtocolOption

type ProtocolOption struct {
	RESTOpts *driver.RESTOptions
	GRPCOpts *driver.GrpcOptions
}

ProtocolOption used to configure rest or grpc options You have to choose between rest or grpc, if your plugin using rest, than ignore grpc option, and vice versa, but you can't ignore them both

type Registry

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

Registry used as wrapper of executor object

func Register

func Register(hostPlugins ...*GoPlugin) *Registry

Register used to collect available hosts and run executor behind it

func (*Registry) Get

func (r *Registry) Get(host, plugin string) (*caller.Plugin, error)

Get plugin's instance. If plugin not started yet, this step will also run the plugin via os subprocess, before using this method you have to make sure that all hosts has been installed

func (*Registry) Install

func (r *Registry) Install() (*Registry, error)

Install used to install available hostPlugins by calling Build

func (*Registry) KillPlugins

func (r *Registry) KillPlugins()

KillPlugins used to kill all plugins from all installed hosts