plugin

Documentation

Overview

Package plugin defines the plugin system built in with the libveinmind SDK, allowing easy integration and composition of hosts and plugins.

This package provides abstraction for callers of plugins, including discovery of plugins, definition of plugin object model and interface to issue plugin commands.

Index

• Constants
• Variables
• func Exec(ctx context.Context, iter ExecIterator, args []string, opts ...ExecOption) error
• func ExecuteStartProcessWithContext(ctx context.Context, _ *Plugin, path string, argv []string, attr *os.ProcAttr) error
• type Command
• type DiscoverHandler
• type DiscoverOption
  • func WithDiscoverHandler(f DiscoverHandler) DiscoverOption
  • func WithDiscoverParallelism(n int) DiscoverOption
  • func WithExecutor(exec Executor) DiscoverOption
  • func WithGlob(pattern string) DiscoverOption
• type ExecGenerator
• type ExecHandler
• type ExecInterceptor
• type ExecIterator
  • func IterateAll(rang ExecRange) (ExecIterator, error)
  • func IterateTyped(rang ExecRange, typ string) (ExecIterator, error)
• type ExecOption
  • func WithExecGenerator(generator ExecGenerator) ExecOption
  • func WithExecHandler(f ExecHandler) ExecOption
  • func WithExecInterceptor(interceptor ExecInterceptor) ExecOption
  • func WithExecOptions(opts ...ExecOption) ExecOption
  • func WithExecParallelism(n int) ExecOption
  • func WithPrependArgs(args ...string) ExecOption
• type ExecRange
• type Executor
• type Manifest
• type Plugin
  • func DiscoverPlugins(ctx context.Context, root string, opts ...DiscoverOption) ([]*Plugin, error)
  • func NewPlugin(ctx context.Context, path string, opts ...DiscoverOption) (*Plugin, error)

Constants

const CurrentManifestVersion = 1

CurrentManifestVersion is the current version of manifest.

The version is maintained by the SDK itself and increments on the schema of plugin.Manifest changes. The version will increment when the newer scheme has newer indispensible items or deleted fields, making it incompatible with older ones. And hosts with different manifest version will not be able to work together.

Variables

var DefaultDiscoverHandler = DiscoverHandler(ignoreDiscoverHandler)

DefaultDiscoverHandler just simply ignore all errors.

var DefaultExecHandler = ExecHandler(ignoreExecHandler)

DefaultExecHandler just simply ignore all errors.

var DefaultExecutor = Executor(executeStartProcess)

Functions

func Exec

func Exec(
	ctx context.Context, iter ExecIterator,
	args []string, opts ...ExecOption,
) error

Exec the plugins specified by iterator with options.

func ExecuteStartProcessWithContext

func ExecuteStartProcessWithContext(
	ctx context.Context, _ *Plugin,
	path string, argv []string, attr *os.ProcAttr) error

Types

type Command

type Command struct {
	Path []string        `json:"path"`
	Type string          `json:"type"`
	Data json.RawMessage `json:"data"`
}

Command describes a callable subcommand with the path to call and its use circumstance.

type DiscoverHandler

type DiscoverHandler func(*Plugin, error) error

DiscoverHandler is the handler for plugin errors in discover.

type DiscoverOption

type DiscoverOption func(*discoverOption)

DiscoverOption specifies how to find and validate plugins.

func WithDiscoverHandler

func WithDiscoverHandler(f DiscoverHandler) DiscoverOption

WithDiscoverHandler specifies the handler of error.

When unspecified, those plugin with error would be ignored, and only successfully discovered ones will be returned.

This option is ignored when used with NewPlugin, since it should return the error when plugin object is not returned.

func WithDiscoverParallelism

func WithDiscoverParallelism(n int) DiscoverOption

WithDiscoverParallelism specifies how many info commands will be executed in parallel.

Leaving parallelism unspecified or setting it to 0 will cause up to runtime.GOMAXPROCS(0) plugins to be executed in parallel. Setting it to 1 will disable parallel execution.

This option is ignored when calling NewPlugin directly.

func WithExecutor

func WithExecutor(exec Executor) DiscoverOption

WithExecutor specifies that the plugin will be executed with the specified option.

func WithGlob

func WithGlob(pattern string) DiscoverOption

WithGlob specifies the pattern of file to find.

While using, the path for matching will be first trimmed relative to the traversal root.

This option is ignored when used with DiscoverPlugin, since it has already specified a file to validate.

type ExecGenerator

type ExecGenerator func(plug *Plugin, c *Command) []ExecOption

ExecGenerator is the function that generates exec options for each plugin and command that is visited.

type ExecHandler

type ExecHandler func(*Plugin, *Command, error) error

ExecHandler is the handler for plugin errors in exec.

type ExecInterceptor

type ExecInterceptor func(
	ctx context.Context, plug *Plugin, c *Command,
	next func(context.Context, ...ExecOption) error,
) error

ExecInterceptor is the function that intercepts how to execute the plugin.

This function creates a responsibility chain, and it should invoke the next function to move on. The arguments generated can also be passed to the next function.

type ExecIterator

type ExecIterator interface {
	HasNext() bool
	Next() (*Plugin, *Command, error)
	Done()
	Reset()
}

ExecIterator is an iterator providing items for executing, and thus allow user to provide the list of plugin to execute in an independent way while visiting.

The Next() method might returns triple nil when it is wrapping and filtering another iterator. This is an expected condition and the caller should handle it.

func IterateAll

func IterateAll(rang ExecRange) (ExecIterator, error)

IterateAll iterates all executable functions in the command.

func IterateTyped

func IterateTyped(rang ExecRange, typ string) (ExecIterator, error)

IterateTyped iterates for commands with type in the function.

type ExecOption

type ExecOption func(*execOption)

ExecOption specifies works to perform when calling a plugin command.

func WithExecGenerator

func WithExecGenerator(generator ExecGenerator) ExecOption

WithExecGenerator specifies a generator for each command.

func WithExecHandler

func WithExecHandler(f ExecHandler) ExecOption

WithExecHandler specifies the handler of error.

When unspecified, those plugin with error would be ignored, and other plugins will be execute on.

Unlike WithDiscoverHandler, the option is also used even if Plugin.Exec is called directly.

func WithExecInterceptor

func WithExecInterceptor(interceptor ExecInterceptor) ExecOption

WithExecInterceptor specifies a interceptor to execute.

func WithExecOptions

func WithExecOptions(opts ...ExecOption) ExecOption

WithExecOptions creates a composite of exec option.

This is useful when external packages want to specify their own exec options and represent them as if only one option dedicated to their command is specified.

func WithExecParallelism

func WithExecParallelism(n int) ExecOption

WithExecParallelism specifies how many commands will be executed in parallel.

Leaving paralellism unspecified or setting it to 0 will cause up to runtime.GOMAXPROCS(0) plugins to be executed in parallel. Setting it to 1 will disable parallel execution.

This option is ignored when calling plugin.Exec directly.

func WithPrependArgs

func WithPrependArgs(args ...string) ExecOption

WithPrependArgs specifies a portion of arguments to prepend to the arguments passed to Plugin.Exec function.

This allows external packages to specifies their own arguments and flags in determined context.

type ExecRange

type ExecRange interface{}

ExecRange specifies a range of plugins to execute.

The type itself is defined as a general interface, but actually accepts only the following types:

• *Plugin
• []*Plugin
• ExecIterator
• func() ExecIterator
• func() (ExecIterator, error)
• interface{ All() ExecIterator }
• interface{ All() (ExecIterator, error) }
• interface{ ExecIterator Typed(string) } (IterateTyped)

All these types can be unified into ExecIterator by calling NewExecIterator so the caller don't have to concern about the difference of acceptable types.

type Executor

type Executor func(
	ctx context.Context, plugin *Plugin,
	path string, argv []string, attr *os.ProcAttr,
) error

Executor will attempt to execute the plugin with given configuration.

Sometimes it takes extra steps to execute the plugin, like switching to specific namespace and so on, and these works will be done with executor.

type Manifest

type Manifest struct {
	Name        string   `json:"name,omitempty"`
	Version     string   `json:"version,omitempty"`
	Author      string   `json:"author,omitempty"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`

	// Auto generated fields that user written values will
	// be overwritten when return.
	ManifestVersion int       `json:"manifestVersion"`
	Commands        []Command `json:"commands,omitempty"`
}

Manifest is the information describing the plugin itself.

type Plugin

type Plugin struct {
	Manifest
	// contains filtered or unexported fields
}

Plugin is the parsed and verified plugin, ready for issuing commands to it.

Upon discovery, the process will attempt to call the "info" subcommand to verify whether the specified executable file is callable, and produces compatible manifest. How to use the plugin depends on the users.

func DiscoverPlugins

func DiscoverPlugins(
	ctx context.Context, root string, opts ...DiscoverOption,
) ([]*Plugin, error)

DiscoverPlugins discover plugins by a traversal under specified directory recursively.

func NewPlugin

func NewPlugin(
	ctx context.Context, path string, opts ...DiscoverOption,
) (*Plugin, error)

NewPlugin attempt to create and verify a plugin.