plugin

package
v1.5.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 28, 2023 License: MIT Imports: 7 Imported by: 24

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

View Source 
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

View Source 
var DefaultDiscoverHandler = DiscoverHandler(ignoreDiscoverHandler)

DefaultDiscoverHandler just simply ignore all errors.

View Source 
var DefaultExecHandler = ExecHandler(ignoreExecHandler)

DefaultExecHandler just simply ignore all errors.

View Source 
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 added in v1.3.3 

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.

Source Files

View all Source files

Directories

Path Synopsis
Package plugin/log provides a common log system that is based on the plugin/service.
 Package plugin/log provides a common log system that is based on the plugin/service.
Package plugin/service provides a common way for host and plugins to communicate in a IPC-like way.
 Package plugin/service provides a common way for host and plugins to communicate in a IPC-like way.
Package specflags provides the flag for specifying plugin specific flags, so that extra arguments might be passed to the matched plugin.
 Package specflags provides the flag for specifying plugin specific flags, so that extra arguments might be passed to the matched plugin.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.