plugin

package
v0.27.2 Latest Latest
Warning

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

 Go to latest Published: Oct 18, 2023 License: Apache-2.0 Imports: 32 Imported by: 4

Documentation

Overview

Package plugin implements ignite plugin management. An ignite plugin is a binary which communicates with the ignite binary via RPC thanks to the github.com/hashicorp/go-plugin library.

Index

Constants

This section is empty.

Variables

View Source 
var PluginsPath = xfilepath.Mkdir(xfilepath.Join(
	config.DirPath,
	xfilepath.Path("plugins"),
))

PluginsPath holds the plugin cache directory.

Functions

func HandshakeConfig 

func HandshakeConfig() plugin.HandshakeConfig

func Scaffold 

func Scaffold(dir, moduleName string, sharedHost bool) (string, error)

Scaffold generates a plugin structure under dir/path.Base(moduleName).

func Update 

func Update(plugins ...*Plugin) error

Update removes the cache directory of plugins and fetch them again.

Types

type Command 

type Command struct {
	// Same as cobra.Command.Use
	Use string
	// Same as cobra.Command.Aliases
	Aliases []string
	// Same as cobra.Command.Short
	Short string
	// Same as cobra.Command.Long
	Long string
	// Same as cobra.Command.Hidden
	Hidden bool
	// Flags holds the list of command flags
	Flags []Flag
	// PlaceCommandUnder indicates where the command should be placed.
	// For instance `ignite scaffold` will place the command at the
	// `scaffold` command.
	// An empty value is interpreted as `ignite` (==root).
	PlaceCommandUnder string
	// List of sub commands
	Commands []Command
}

Command represents a plugin command.

func (Command) PlaceCommandUnderFull 

func (c Command) PlaceCommandUnderFull() string

PlaceCommandUnderFull returns a normalized p.PlaceCommandUnder, by adding the `ignite ` prefix if not present.

func (Command) ToCobraCommand 

func (c Command) ToCobraCommand() (*cobra.Command, error)

ToCobraCommand turns Command into a cobra.Command so it can be added to a parent command.

type ExecutedCommand 

type ExecutedCommand struct {
	// Use is copied from Command.Use
	Use string
	// Path contains the command path, e.g. `ignite scaffold foo`
	Path string
	// Args are the command arguments
	Args []string
	// Full list of args taken from os.Args
	OSArgs []string
	// With contains the plugin config parameters
	With map[string]string
	// contains filtered or unexported fields
}

ExecutedCommand represents a plugin command under execution.

func (*ExecutedCommand) Flags 

func (c *ExecutedCommand) Flags() *pflag.FlagSet

Flags gives access to the commands' flags, like cobra.Command.Flags.

func (*ExecutedCommand) GobDecode 

func (c *ExecutedCommand) GobDecode(bz []byte) error

GobDecode implements gob.Decoder. It actually decodes a gobCommandContext struct and fills c with it.

func (ExecutedCommand) GobEncode 

func (c ExecutedCommand) GobEncode() ([]byte, error)

GobEncode implements gob.Encoder. It actually encodes a gobCommandContext struct built from c.

func (*ExecutedCommand) PersistentFlags 

func (c *ExecutedCommand) PersistentFlags() *pflag.FlagSet

PersistentFlags gives access to the commands' persistent flags, like cobra.Command.PersistentFlags.

func (*ExecutedCommand) SetFlags 

func (c *ExecutedCommand) SetFlags(cmd *cobra.Command)

SetFlags set the flags. As a plugin developer, you probably don't need to use it.

type ExecutedHook 

type ExecutedHook struct {
	// ExecutedCommand gives access to the command attached by the hook.
	ExecutedCommand ExecutedCommand
	// Hook is a copy of the original Hook defined in the Manifest.
	Hook
}

ExecutedHook represents a plugin hook under execution.

type Flag 

type Flag struct {
	Name      string // name as it appears on command line
	Shorthand string // one-letter abbreviated flag
	Usage     string // help message
	DefValue  string // default value (as text); for usage message
	Type      FlagType
	Value     string
	// Persistent indicates wether or not the flag is propagated on children
	// commands
	Persistent bool
}

Flag is a serializable representation of pflag.Flag.

type FlagType 

type FlagType string

FlagType represents the pflag.Flag.Value.Type(). 

const (
	// NOTE(tb): we declare only the main used cobra flag types for simplicity
	// If a plugin receives an unhandled type, it will output an error.
	FlagTypeString      FlagType = "string"
	FlagTypeInt         FlagType = "int"
	FlagTypeUint        FlagType = "uint"
	FlagTypeInt64       FlagType = "int64"
	FlagTypeUint64      FlagType = "uint64"
	FlagTypeBool        FlagType = "bool"
	FlagTypeStringSlice FlagType = "stringSlice"
)

type Hook 

type Hook struct {
	// Name identifies the hook for the client to invoke the correct hook
	// must be unique
	Name string
	// PlaceHookOn indicates the command to register the hooks for
	PlaceHookOn string
}

Hook represents a user defined action within a plugin.

func (Hook) PlaceHookOnFull 

func (h Hook) PlaceHookOnFull() string

PlaceHookOnFull returns a normalized p.PlaceCommandUnder, by adding the `ignite ` prefix if not present.

type Interface 

type Interface interface {
	// Manifest declares the plugin's Command(s) and Hook(s).
	Manifest() (Manifest, error)

	// Execute will be invoked by ignite when a plugin Command is executed.
	// It is global for all commands declared in Manifest, if you have declared
	// multiple commands, use cmd.Path to distinguish them.
	Execute(cmd ExecutedCommand) error

	// ExecuteHookPre is invoked by ignite when a command specified by the Hook
	// path is invoked.
	// It is global for all hooks declared in Manifest, if you have declared
	// multiple hooks, use hook.Name to distinguish them.
	ExecuteHookPre(hook ExecutedHook) error
	// ExecuteHookPost is invoked by ignite when a command specified by the hook
	// path is invoked.
	// It is global for all hooks declared in Manifest, if you have declared
	// multiple hooks, use hook.Name to distinguish them.
	ExecuteHookPost(hook ExecutedHook) error
	// ExecuteHookCleanUp is invoked by ignite when a command specified by the
	// hook path is invoked. Unlike ExecuteHookPost, it is invoked regardless of
	// execution status of the command and hooks.
	// It is global for all hooks declared in Manifest, if you have declared
	// multiple hooks, use hook.Name to distinguish them.
	ExecuteHookCleanUp(hook ExecutedHook) error
}

An ignite plugin must implements the Plugin interface.

type InterfacePlugin 

type InterfacePlugin struct {
	// Impl Injection
	Impl Interface
}

This is the implementation of plugin.Interface so we can serve/consume this

This has two methods: Server must return an RPC server for this plugin type. We construct a InterfaceRPCServer for this.

Client must return an implementation of our interface that communicates over an RPC client. We return InterfaceRPC for this.

Ignore MuxBroker. That is used to create more multiplexed streams on our plugin connection and is a more advanced use case.

func (InterfacePlugin) Client 

func (InterfacePlugin) Client(_ *plugin.MuxBroker, c *rpc.Client) (interface{}, error)

func (*InterfacePlugin) Server 

func (p *InterfacePlugin) Server(*plugin.MuxBroker) (interface{}, error)

type InterfaceRPC 

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

InterfaceRPC is an implementation that talks over RPC.

func (*InterfaceRPC) Execute 

func (g *InterfaceRPC) Execute(c ExecutedCommand) error

Execute implements Interface.Commands.

func (*InterfaceRPC) ExecuteHookCleanUp 

func (g *InterfaceRPC) ExecuteHookCleanUp(hook ExecutedHook) error

func (*InterfaceRPC) ExecuteHookPost 

func (g *InterfaceRPC) ExecuteHookPost(hook ExecutedHook) error

func (*InterfaceRPC) ExecuteHookPre 

func (g *InterfaceRPC) ExecuteHookPre(hook ExecutedHook) error

func (*InterfaceRPC) Manifest 

func (g *InterfaceRPC) Manifest() (Manifest, error)

Manifest implements Interface.Manifest.

type InterfaceRPCServer 

type InterfaceRPCServer struct {
	// This is the real implementation
	Impl Interface
}

InterfaceRPCServer is the RPC server that InterfaceRPC talks to, conforming to the requirements of net/rpc.

func (*InterfaceRPCServer) Execute 

func (s *InterfaceRPCServer) Execute(args map[string]interface{}, _ *interface{}) error

func (*InterfaceRPCServer) ExecuteHookCleanUp 

func (s *InterfaceRPCServer) ExecuteHookCleanUp(args map[string]interface{}, _ *interface{}) error

func (*InterfaceRPCServer) ExecuteHookPost 

func (s *InterfaceRPCServer) ExecuteHookPost(args map[string]interface{}, _ *interface{}) error

func (*InterfaceRPCServer) ExecuteHookPre 

func (s *InterfaceRPCServer) ExecuteHookPre(args map[string]interface{}, _ *interface{}) error

func (*InterfaceRPCServer) Manifest 

func (s *InterfaceRPCServer) Manifest(_ interface{}, resp *Manifest) error

type Manifest 

type Manifest struct {
	Name string
	// Commands contains the commands that will be added to the list of ignite
	// commands. Each commands are independent, for nested commands use the
	// inner Commands field.
	Commands []Command
	// Hooks contains the hooks that will be attached to the existing ignite
	// commands.
	Hooks []Hook
	// SharedHost enables sharing a single plugin server across all running instances
	// of a plugin. Useful if a plugin adds or extends long running commands
	//
	// Example: if a plugin defines a hook on `ignite chain serve`, a plugin server is instanciated
	// when the command is run. Now if you want to interact with that instance from commands
	// defined in that plugin, you need to enable `SharedHost`, or else the commands will just
	// instantiate separate plugin servers.
	//
	// When enabled, all plugins of the same `Path` loaded from the same configuration will
	// attach it's rpc client to a an existing rpc server.
	//
	// If a plugin instance has no other running plugin servers, it will create one and it will be the host.
	SharedHost bool `yaml:"shared_host"`
}

Manifest represents the plugin behavior.

func (*Manifest) ImportCobraCommand 

func (m *Manifest) ImportCobraCommand(c *cobra.Command, placeCommandUnder string)

ImportCobraCommand allows to hydrate m with a standard root cobra commands.

type Option 

type Option func(*Plugin)

Option configures Plugin.

func CollectEvents 

func CollectEvents(ev events.Bus) Option

CollectEvents collects events from the chain.

type Plugin 

type Plugin struct {
	// Embed the plugin configuration
	pluginsconfig.Plugin
	// Interface allows to communicate with the plugin via net/rpc.
	Interface Interface
	// If any error occurred during the plugin load, it's stored here
	Error error
	// contains filtered or unexported fields
}

Plugin represents a ignite plugin.

func Load 

func Load(ctx context.Context, plugins []pluginsconfig.Plugin, options ...Option) ([]*Plugin, error)

Load loads the plugins found in the chain config.

There's 2 kinds of plugins, local or remote. Local plugins have their path starting with a `/`, while remote plugins don't. Local plugins are useful for development purpose. Remote plugins require to be fetched first, in $HOME/.ignite/plugins folder, then they are loaded from there.

If an error occurs during a plugin load, it's not returned but rather stored in the Plugin.Error field. This prevents the loading of other plugins to be interrupted.

func (*Plugin) KillClient 

func (p *Plugin) KillClient()

KillClient kills the running plugin client.

Source Files

View all Source files

Directories

Path Synopsis

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.