pluginutil

Documentation

Index

• func BuildPluginMap(opt ...Option) (map[string]*PluginInfo, error)
• func CreatePlugin(plugin *PluginInfo, opt ...Option) (interface{}, func() error, error)
• func GetOpts(opt ...Option) (*options, error)
• type InmemCreationFunc
• type Option
  • func WithPluginClientCreationFunc(with PluginClientCreationFunc) Option
  • func WithPluginExecutionDirectory(with string) Option
  • func WithPluginsFilesystem(withPrefix string, withPlugins fs.FS) Option
  • func WithPluginsMap(with map[string]InmemCreationFunc) Option
  • func WithSecureConfig(with *gp.SecureConfig) Option
• type PluginClientCreationFunc
• type PluginInfo

Functions

func BuildPluginMap

func BuildPluginMap(opt ...Option) (map[string]*PluginInfo, error)

BuildPluginMap takes in options that contain one or more sets of plugin maps or filesystems and builds an overall mapping of a plugin name to its information. The desired plugin can then be sent to CreatePlugin to actually instantiate it. If a plugin is specified by name multiple times in option, the last one wins.

func CreatePlugin

func CreatePlugin(plugin *PluginInfo, opt ...Option) (interface{}, func() error, error)

CreatePlugin instantiates a given plugin either via an in-memory function or by executing a go-plugin plugin. The interface returned will either be a *<go-plugin>.Client or the value returned from an in-memory function. A type switch should be used by the calling code to determine this, and the appropriate service should be Dispensed if what is returned is a go-plugin plugin.

If the WithSecureConfig option is passed, this will be round-tripped into the PluginClientCreationFunction from the given *PluginInfo, where it can be sent into the go-plugin client configuration.

The caller should ensure that cleanup() is executed when they are done using the plugin. In the case of an in-memory plugin it will be nil, however, if the plugin is via RPC it will ensure that it is torn down properly.

func GetOpts

func GetOpts(opt ...Option) (*options, error)

GetOpts - iterate the inbound Options and return a struct

Types

type InmemCreationFunc

type InmemCreationFunc func() (interface{}, error)

InmemCreationFunc is a function that, when run, returns the thing you want created (almost certainly an interface that is also supported by a go-plugin plugin implementation)

type Option

type Option func(*options) error

Option - how Options are passed as arguments

func WithPluginClientCreationFunc

func WithPluginClientCreationFunc(with PluginClientCreationFunc) Option

WithPluginClientCreationFunc allows passing in the func to use to create a plugin client on the host side. Not necessary if only inmem functions are used, but required otherwise.

func WithPluginExecutionDirectory

func WithPluginExecutionDirectory(with string) Option

WithPluginExecutionDirectory allows setting a specific directory for writing out and executing plugins; if not set, os.TempDir will be used to create a suitable directory

func WithPluginsFilesystem

func WithPluginsFilesystem(withPrefix string, withPlugins fs.FS) Option

WithPluginsFilesystem provides an fs.FS containing plugins that can be executed to provide functionality. This can be specified multiple times; all FSes will be scanned. Any conflicts will be resolved later (e.g. in BuildPluginsMap, the behavior will be last scanned plugin with the same name wins).If there are conflicts, the last one wins, a property shared with WithPluginsMap). The prefix will be stripped from each entry when determining the plugin type.

func WithPluginsMap

func WithPluginsMap(with map[string]InmemCreationFunc) Option

WithPluginsMap provides a map containing functions that can be called to instantiate plugins directly. This can be specified multiple times; all maps will be scanned. Any conflicts will be resolved later (e.g. in BuildPluginsMap, the behavior will be last scanned plugin with the same name wins).If there are conflicts, the last one wins, a property shared with WithPluginsFilesystem).

func WithSecureConfig

func WithSecureConfig(with *gp.SecureConfig) Option

WithSecureConfig allows passing in the go-plugin secure config struct for validating a plugin prior to execution. Generally not needed if the plugin is being spun out of the binary at runtime.

type PluginClientCreationFunc

type PluginClientCreationFunc func(string, ...Option) (*gp.Client, error)

PluginClientCreationFunc is a function that, when run, returns a client corresponding to a spun out go-plugin plugin. The string argument is the filename. WithSecureConfig is supported as an option that will be round tripped to the given function if provided to this package so that it can be given to go-plugin.

type PluginInfo

type PluginInfo struct {
	ContainerFs              fs.FS
	Filename                 string
	InmemCreationFunc        InmemCreationFunc
	PluginClientCreationFunc PluginClientCreationFunc
}

PluginInfo contains plugin instantiation information for a single plugin, parsed from the various maps and FSes that can be input to the BuildPluginMap function.