pluginfx

README

pluginfx

pluginfx does something good.

Setup

1. Search and replace pluginfx with your project name.
2. Initialize go.mod file: go mod init github.com/xmidt-org/pluginfx
3. Add org teams to project (Settings > Manage Access):
   • xmidt-org/admins with Admin role
   • xmidt-org/server-writers with Write role
4. Manually create the first release. After v0.0.1 exists, other releases will be made by automation after the CHANGELOG is updated to reflect a new version header and nothing under the Unreleased header.
5. For libraries:
   1. Add org workflows in dir .github/workflows: push, tag, and release. This can be done by going to the Actions tab for the repo on the github site.
   2. Remove the following files/dirs: .dockerignore, Dockerfile, Makefile, rpkg.macros, pluginfx.yaml, deploy/, and conf/.
6. For applications:
   1. Remove PkgGoDev badge from this file.
   2. Add org workflows in dir .github/workflows: push, tag, release, and docker-release. This can be done by going to the Actions tab for the repo on the github site.
   3. Add project name, .ignore, and errors.txt to .gitignore file.
   4. Update Dockerfile - choose new ports to expose that no current XMiDT application is using.
   5. Update deploy/packaging/pluginfx.spec file to have a proper Summary and Description.
   6. Update conf/pluginfx.service file to have a proper Description.

Summary

Summary should be a small paragraph explanation of what this project does.

Table of Contents

• Code of Conduct
• Details
• Install
• Contributing

Code of Conduct

This project and everyone participating in it are governed by the XMiDT Code Of Conduct. By participating, you agree to this Code.

Details

Add details here.

Install

Add details here.

Contributing

Refer to CONTRIBUTING.md.

Documentation

Index

• func EachSymbol(s Symbols, sv SymbolVisitor, names ...string) error
• func Lookup(s Symbols, name string) (interface{}, error)
• func LookupConstructor(s Symbols, name string) (reflect.Value, error)
• func LookupLifecycle(s Symbols, name string) (func(context.Context) error, error)
• type InvalidConstructorError
  • func (ice *InvalidConstructorError) Error() string
• type InvalidLifecycleError
  • func (ile *InvalidLifecycleError) Error() string
• type MissingSymbolError
  • func (mse *MissingSymbolError) Error() string
  • func (mse *MissingSymbolError) Unwrap() error
• type Plugin
  • func (pl Plugin) Provide() fx.Option
• type Set
  • func (s Set) Provide() fx.Option
• type SymbolMap
  • func (sm *SymbolMap) Del(name string)
  • func (sm SymbolMap) Lookup(name string) (plugin.Symbol, error)
  • func (sm *SymbolMap) Set(name string, value plugin.Symbol)
  • func (sm *SymbolMap) SetValue(name string, value interface{})
• type SymbolVisitor
• type Symbols

Functions

func EachSymbol

func EachSymbol(s Symbols, sv SymbolVisitor, names ...string) error

EachSymbol applies a visitor over a set of symbols.

func Lookup

func Lookup(s Symbols, name string) (interface{}, error)

Lookup invokes s.Lookup and normalizes any error to *MissingSymbolError.

func LookupConstructor

func LookupConstructor(s Symbols, name string) (reflect.Value, error)

func LookupLifecycle

func LookupLifecycle(s Symbols, name string) (func(context.Context) error, error)

Types

type InvalidConstructorError

type InvalidConstructorError struct {
	Name string
	Type reflect.Type
}

InvalidConstructorError indicates that a symbol was not usable as an uber/fx constructor.

func (*InvalidConstructorError) Error

func (ice *InvalidConstructorError) Error() string

type InvalidLifecycleError

type InvalidLifecycleError struct {
	Name string
	Type reflect.Type
}

InvalidLifecycleError indicates that a symbol was not usable as an uber/fx lifecycle callback via fx.Hook.

func (*InvalidLifecycleError) Error

func (ile *InvalidLifecycleError) Error() string

type MissingSymbolError

type MissingSymbolError struct {
	Name string
	Err  error
}

MissingSymbolError indicates that a symbol was not found.

*plugin.Plugin does not return this error. It returns a generated using fmt.Errorf. This package's code normalizes these errors to errors of this type.

func (*MissingSymbolError) Error

func (mse *MissingSymbolError) Error() string

func (*MissingSymbolError) Unwrap

func (mse *MissingSymbolError) Unwrap() error

type Plugin

type Plugin struct {
	// Name is the optional name of the plugin component within the application.  This
	// field is ignored if Anonymous is set.
	Name string

	// Group is the optional value group to place the loaded plugin into.  This field
	// is ignored if Anonymous is set.
	Group string

	// Anonymous controls whether the plugin itself is provided as a component
	// to the enclosing fx.App.  If this field is true, then the plugin is not
	// placed into the fx.App regardless of the values of Name and Group.
	Anonymous bool

	// Path is the plugin's path.  This field is required.
	Path string

	// IgnoreMissingConstructors controls what happens if a symbol in the Constructors
	// field is not present in the plugin.  If this field is true, missing constructor
	// symbols are silently ignored.  Otherwise, missing constructor symbols will shortcircuit
	// application startup with one or more errors.
	IgnoreMissingConstructors bool

	// Constructors are the optional exported functions from the plugin that participate
	// in dependency injection.  Each constructor is passed to fx.Provide.
	Constructors []string

	// IgnoreMissingLifecycle controls what happens if OnStart or OnStop are not symbols
	// in the plugin.  If this field is true and either OnStart or OnStop are not present,
	// no error is raised.  Otherwise, application startup is shortcircuited with one or
	// more errors.
	IgnoreMissingLifecycle bool

	// OnStart is the optional exported function that should be called when the enclosing
	// application is started.
	OnStart string

	// OnStop is the optional exported function that should be called when the enclosing
	// application is stopped.
	OnStop string
}

Plugin describes how to load a single plugin and integrate it into an enclosing fx.App.

func (Plugin) Provide

func (pl Plugin) Provide() fx.Option

Provide builds the appropriate options to integrate this plugin into an enclosing fx.App.

Typical usage:

app := fx.New(
  pluginx.Plugin{
    Path: "/etc/lib/something.so",
    Constructors: []string{"ProvideSomething", "NewSomethingElse"},
    OnStart: "Initialize",
    /* other fields filled out as desired */
  }.Provide()
)

type Set

type Set struct {
	// Group is the optional value group to place each plugin in this set into.  If this
	// field is unset, the loaded plugins are not added as components.
	Group string

	// Paths are the plugin paths to load.
	Paths []string

	// IgnoreMissingConstructors controls what happens if a symbol in the Constructors
	// field is not present in any of the plugins.  If this field is true, missing constructor
	// symbols are silently ignored.  Otherwise, missing constructor symbols will shortcircuit
	// application startup with one or more errors.
	IgnoreMissingConstructors bool

	// Constructors are the optional exported functions from each plugin that participate
	// in dependency injection.  Each constructor is passed to fx.Provide.
	Constructors []string

	// IgnoreMissingLifecycle controls what happens if OnStart or OnStop are not symbols
	// in each plugin.  If this field is true and either OnStart or OnStop are not present,
	// no error is raised.  Otherwise, application startup is shortcircuited with one or
	// more errors.
	IgnoreMissingLifecycle bool

	// OnStart is the optional exported function that should be called when the enclosing
	// application is started.
	OnStart string

	// OnStop is the optional exported function that should be called when the enclosing
	// application is stopped.
	OnStop string
}

Set describes how to load multiple plugins as a bundle and integrate each of them into an enclosing fx.App.

func (Set) Provide

func (s Set) Provide() fx.Option

type SymbolMap

type SymbolMap map[string]plugin.Symbol

SymbolMap is a map implementation of Symbols. It allows for an in-memory implementation of a plugin for testing or for production defaults.

The zero value of this type is a usable, empty "plugin".

func (*SymbolMap) Del

func (sm *SymbolMap) Del(name string)

Del removes a symbol from this map.

func (SymbolMap) Lookup

func (sm SymbolMap) Lookup(name string) (plugin.Symbol, error)

Lookup implements the Symbols interface.

func (*SymbolMap) Set

func (sm *SymbolMap) Set(name string, value plugin.Symbol)

Set establishes a symbol, overwriting any existing symbol with the given name. This method panics if value is not a function or a non-nil pointer, which are the only allowed types of symbols in an actual plugin.

func (*SymbolMap) SetValue

func (sm *SymbolMap) SetValue(name string, value interface{})

SetValue is similar to Set, but does not panic if value is not a function or a pointer. Instead, in that case this method creates a pointer to the value and use that pointer as the value. This method will still panic if value is a nil pointer, however.

type SymbolVisitor

type SymbolVisitor func(symbolName string, value reflect.Value, lookupErr error) error

SymbolVisitor is a callback for symbols. If an error is returned from Lookup, this callback is passed and invalid value along with that error. Otherwise, this callback is passed the value of the symbol, and lookupErr will be nil.

If this callback itself returns an error, then visitation is halted and that error is returned.

type Symbols

type Symbols interface {
	// Lookup returns the value of the given symbol, or an error
	// if no such symbol exists.
	Lookup(string) (plugin.Symbol, error)
}

Symbols defines the behavior of something that can look up exported symbols. *plugin.Plugin implements this interface.