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 HashMethod
• type InmemCreationFunc
• type Option
  • func WithPluginClientCreationFunc(with PluginClientCreationFunc) Option
  • func WithPluginExecutionDirectory(with string) Option
  • func WithPluginFile(with PluginFileInfo) 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 PluginFileInfo
• 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 HashMethod

type HashMethod string

HashMethod is a string representation of a hash method

const (
	HashMethodUnspecified HashMethod = ""
	HashMethodSha2256     HashMethod = "sha2-256"
	HashMethodSha2384     HashMethod = "sha2-384"
	HashMethodSha2512     HashMethod = "sha2-512"
	HashMethodSha3256     HashMethod = "sha3-256"
	HashMethodSha3384     HashMethod = "sha3-384"
	HashMethodSha3512     HashMethod = "sha3-512"
)

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 WithPluginFile

func WithPluginFile(with PluginFileInfo) Option

WithPluginFile provides source information for a file on disk (rather than an fs.FS abstraction or an in-memory function). Secure hash info _must_ be provided in this case. If there are conflicts with the name, the last one wins, a property shared with WithPluginsFilesystem and WithPluginsMap).

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 and WithPluginFile). The prefix will be stripped from each entry when determining the plugin type.

This doesn't currently support any kind of secure config and is meant for cases where you can build up this FS securely. See WithPluginFile for adding individual files with checksumming.

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 and WithPluginFile).

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 PluginFileInfo

type PluginFileInfo struct {
	Name       string
	Path       string
	Checksum   []byte
	HashMethod HashMethod
}

PluginFileInfo represents user-specified on-disk file information. Note that testing for how this works in go-plugin, e.g. passing it into SecureConfig, is in configutil to avoid pulling in go-kms-wrapping as a dep of this package.

type PluginInfo

type PluginInfo struct {
	ContainerFs              fs.FS
	Path                     string
	SecureConfig             *gp.SecureConfig
	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.