plugin

README

Plugins

Check out the plugin demos.

Analyze Go code to bundle controller factories into Plugin modules.

Features:

• Scan packages for ControllerBus factories to include
• Automatically codegen and compile modules for all targets
• Full support for Go modules and module replacements
• Manifest of all currently loaded plugins
• Detect Go module code changes and hot-reload
• Multiple bundling and plugin loading approaches

Using the IPC system, a plugin can also be loaded as a sub-process communicating over stdin/stdout (or named pipes on Windows).

Codegen Output Example

Example generated code for a plugin:

// +build controllerbus_plugin

package main

import (
	"github.com/aperturerobotics/controllerbus/bus"
	"github.com/aperturerobotics/controllerbus/controller"
	boilerplate_controller "cbus-plugin-abcdef/github.com/aperturerobotics/controllerbus/example/boilerplate/controller"
	hot_compile_demo_controller "cbus-plugin-abcdef/github.com/aperturerobotics/controllerbus/example/plugin-demo/demo-controller"
	"github.com/aperturerobotics/controllerbus/plugin"
)

// BinaryID is the binary identifier.
const (
	BinaryID	= "hot-demo-module"
	BinaryVersion	= "cbus-plugin-abcdef"
)

// BinaryFactories are the factories included in the binary.
var BinaryFactories = func(b bus.Bus) []controller.Factory {
	return []controller.Factory{boilerplate_controller.NewFactory(b), hot_compile_demo_controller.NewFactory(b)}
}

// Plugin is the top-level static plugin container.
type Plugin = plugin.StaticPlugin

// NewPlugin constructs the static container plugin.
func NewPlugin() *Plugin {
	return plugin.NewStaticPlugin(BinaryID, BinaryVersion, BinaryFactories)
}

// ControllerBusPlugin is the variable read by the plugin loader.
var (
	ControllerBusPlugin	plugin.Plugin	= NewPlugin()
	_			plugin.Plugin	= ((*Plugin)(nil))
	HotPluginBuildPrefix			= "cbus-plugin-abcdef"
)

var HotPluginBuildUUID = `cbus-plugin-abcdef`

Documentation

Index

• Constants
• Variables
• type FactoryCtorSet
• type Plugin
• type PluginResolver
• type Resolver
  • func NewResolver(ctx context.Context, bus bus.Bus, pluginBinaryID string, ...) *Resolver
  • func (r *Resolver) GetConfigCtorByID(ctx context.Context, id string) (config.Constructor, error)
  • func (r *Resolver) GetFactoryMatchingConfig(ctx context.Context, c config.Config) (controller.Factory, error)
  • func (r *Resolver) GetResolverID() string
  • func (r *Resolver) GetResolverVersion() semver.Version
  • func (r *Resolver) PrePluginUnload()
• type StaticPlugin
  • func NewStaticPlugin(binaryID string, binaryVersion string, factories FactoryCtorSet) *StaticPlugin
  • func (e *StaticPlugin) GetBinaryID() string
  • func (e *StaticPlugin) GetBinaryVersion() string
  • func (e *StaticPlugin) NewPluginResolver(ctx context.Context, b bus.Bus) (PluginResolver, error)
  • func (e *StaticPlugin) PrePluginUnload()
• type StaticPluginFactory
  • func NewStaticPluginFactory(ctx context.Context, ft controller.Factory, binaryID string, bus bus.Bus) *StaticPluginFactory
  • func (s *StaticPluginFactory) Close()
  • func (s *StaticPluginFactory) Construct(conf config.Config, opts controller.ConstructOpts) (controller.Controller, error)
  • func (s *StaticPluginFactory) GetFactoryContext() context.Context
• type UnloadHandler

Constants

const PluginGlobalVar = "ControllerBusPlugin"

PluginGlobalVar is the global var in plugin bundles.

Variables

var Version = semver.MustParse("0.0.1")

Version is the resolver version.

Types

type FactoryCtorSet

type FactoryCtorSet = func(b bus.Bus) []controller.Factory

FactoryCtorSet is a list of factory constructors.

type Plugin

type Plugin interface {
	// UnloadHandler indicates plugin implements pre-plugin unload
	UnloadHandler

	// GetBinaryID returns the plugin binary ID.
	// Usually the go.mod package name.
	GetBinaryID() string
	// GetBinaryVersion returns the plugin binary version
	// Does not need to be semver (usually uses Go.mod versioning)
	GetBinaryVersion() string
	// NewPluginResolver constructs the resolver and inits the plugin.
	// ctx is canceled when the plugin is about to be unloaded.
	NewPluginResolver(ctx context.Context, bus bus.Bus) (PluginResolver, error)
}

Plugin is the top-level type exposed in a Hot binary.

type PluginResolver

type PluginResolver interface {
	// FactoryResolver indicates this implements FactoryResolver.
	controller.FactoryResolver
	// UnloadHandler indicates resolver implements pre-plugin unload
	UnloadHandler
}

PluginResolver resolves types included in a binary.

type Resolver

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

Resolver implements the controller resolver using a list of built-in controller implementations.

Does not require semantic versioning for binary versions.

func NewResolver

func NewResolver(
	ctx context.Context,
	bus bus.Bus,
	pluginBinaryID string,
	pluginBinaryVersion string,
	factories ...controller.Factory,
) *Resolver

NewResolver constructs a new resolver with a plugin binary.

func (*Resolver) GetConfigCtorByID

func (r *Resolver) GetConfigCtorByID(
	ctx context.Context, id string,
) (config.Constructor, error)

GetConfigCtorByID returns a config constructor matching the ID. If none found, return nil, nil

func (*Resolver) GetFactoryMatchingConfig

func (r *Resolver) GetFactoryMatchingConfig(
	ctx context.Context, c config.Config,
) (controller.Factory, error)

GetFactoryMatchingConfig returns the factory that matches the config. If no factory is found, return nil. If an unexpected error occurs, return it.

func (*Resolver) GetResolverID

func (r *Resolver) GetResolverID() string

GetResolverID returns the resolver identifier.

func (*Resolver) GetResolverVersion

func (r *Resolver) GetResolverVersion() semver.Version

GetResolverVersion returns the resolver version.

func (*Resolver) PrePluginUnload

func (r *Resolver) PrePluginUnload()

PrePluginUnload is called just before the plugin is unloaded.

type StaticPlugin

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

StaticPlugin contains a compiled set of controller factories.

func NewStaticPlugin

func NewStaticPlugin(
	binaryID string,
	binaryVersion string,
	factories FactoryCtorSet,
) *StaticPlugin

NewStaticPlugin constructs a new static plugin.

func (*StaticPlugin) GetBinaryID

func (e *StaticPlugin) GetBinaryID() string

GetBinaryID returns the plugin binary ID. Usually the go.mod package name.

func (*StaticPlugin) GetBinaryVersion

func (e *StaticPlugin) GetBinaryVersion() string

GetBinaryVersion returns the plugin binary version Does not need to be semver (usually uses Go.mod versioning)

func (*StaticPlugin) NewPluginResolver

func (e *StaticPlugin) NewPluginResolver(ctx context.Context, b bus.Bus) (PluginResolver, error)

NewPluginResolver constructs the resolver and inits the plugin. ctx is canceled when the plugin is about to be unloaded.

func (*StaticPlugin) PrePluginUnload

func (e *StaticPlugin) PrePluginUnload()

PrePluginUnload is called just before the plugin is unloaded.

type StaticPluginFactory

type StaticPluginFactory struct {
	controller.Factory
	// contains filtered or unexported fields
}

StaticPluginFactory wraps a factory with a pre-close hook.

func NewStaticPluginFactory

func NewStaticPluginFactory(
	ctx context.Context,
	ft controller.Factory,
	binaryID string,
	bus bus.Bus,
) *StaticPluginFactory

NewStaticPluginFactory constructs a new static plugin factory.

func (*StaticPluginFactory) Close

func (s *StaticPluginFactory) Close()

Close closes the static plugin factory.

func (*StaticPluginFactory) Construct

func (s *StaticPluginFactory) Construct(
	conf config.Config,
	opts controller.ConstructOpts,
) (controller.Controller, error)

Construct constructs the associated controller given configuration.

func (*StaticPluginFactory) GetFactoryContext

func (s *StaticPluginFactory) GetFactoryContext() context.Context

GetContext returns a context that is canceled if the factory is unloaded.

type UnloadHandler

type UnloadHandler interface {
	// PrePluginUnload is called just before the plugin is unloaded.
	//
	// Unloading:
	// 1. context is canceled.
	// 2. PrePluginUnload called on all resolvers.
	// 3. PrePluginUnload called on plugin
	// 4. Unload of plugin
	PrePluginUnload()
}

UnloadHandler is called before the plugin is unloaded.