plugo

README

Plugo

A plugin library for Go, designed with ease of use and minimal boilerplate in mind.

How does it work?

This library implements plugins as separate processes. Both the host process and the plugin process(es) are abstracted into what this library defines as 'plugos'. A plugo is a server that communicates with other plugos in order to provide the features of a traditional plugin system such as those available in Java. Plugos are built into executables using go build and then dragged into a folder within their parent's directory. The name of this folder depends on the name specified by the developer of the parent plugo. See the example/parent/plugos folder.

Working example

There is a working, thoroughly commented example of plugos in the /example directory. The parent plugo is the host process, and the child plugo is its plugin. The child has been compiled into an executable using go build and copied into the the parent's 'plugos' folder, where it's started by the parent. The parent can be run by running go run ., and its interactions with the child plugo will be printed out in the terminal.

Limitations

Any values that can be encoded and decoded with encoding/gob can be sent as arguments to, or returned as values by, an exposed function. This includes structs. Error types cannot be encoded as types using encoding/gob, however, if the last returned value of an exposed function is of type error, then it can be received by the calling plugo in the error value returned by p.Call(), p.CallWithContext() and p.CallWithTimeout().

Planned features

• Secure communication between plugos using encryption
• Exposing functions via structs

Comments

If your intent is to use this library to create a plugin system for a Go project so that other developers can extend that Go project, then I highly suggest that you do not directly expose your developers to Plugo, but instead create wrapper functions around plugo functions and have your plugin developers use those. An example of this is my own project, Jukebox. Jukebox is a Minecraft server that supports plugins written in Go, however, the plugo library is abstracted away by what I call the Disc API, so from a plugin developer's perspective, the code they write is being executed on the main process directly.

Documentation

Index

• type Plugo
  • func New(plugoId string) (*Plugo, error)
  • func (plugo *Plugo) Call(plugoId string, functionId string, arguments ...any) ([]any, error)
  • func (plugo *Plugo) CallWithContext(plugoId, functionId string, ctx context.Context, arguments ...any) ([]any, error)
  • func (plugo *Plugo) CallWithTimeout(plugoId string, functionId string, milliseconds int, arguments ...any) ([]any, error)
  • func (plugo *Plugo) CheckConnection(connectedPlugoId string) bool
  • func (plugo *Plugo) Expose(function any)
  • func (plugo *Plugo) ExposeId(functionId string, function any)
  • func (plugo *Plugo) Println(args ...any)
  • func (plugo *Plugo) Ready(functionId string) error
  • func (plugo *Plugo) Shutdown()
  • func (plugo *Plugo) StartChildren(folderName string) error
  • func (plugo *Plugo) Unexpose(functionId string)

Types

type Plugo

type Plugo struct {
	Id       string
	ParentId string

	MemoryAllocation int
	// contains filtered or unexported fields
}

func New

func New(plugoId string) (*Plugo, error)

This function creates a plugo. plugoId should be unique to avoid conflicts with other plugos.

func (*Plugo) Call

func (plugo *Plugo) Call(
	plugoId string,
	functionId string,
	arguments ...any,
) ([]any, error)

func (*Plugo) CallWithContext

func (plugo *Plugo) CallWithContext(
	plugoId,
	functionId string,
	ctx context.Context,
	arguments ...any,
) ([]any, error)

This function attempts to call a function with Id functionId exposed by a plugo with Id plugoId with arguments.

func (*Plugo) CallWithTimeout

func (plugo *Plugo) CallWithTimeout(
	plugoId string,
	functionId string,
	milliseconds int,
	arguments ...any,
) ([]any, error)

func (*Plugo) CheckConnection

func (plugo *Plugo) CheckConnection(connectedPlugoId string) bool

func (*Plugo) Expose

func (plugo *Plugo) Expose(function any)

This function exposes the given function to connected plugos. If f is of type func(...any) []any it will be not be called using reflect, resulting in better performance. functionId is the Id through which other plugos may call the function using the plugo.Call() function.

func (*Plugo) ExposeId

func (plugo *Plugo) ExposeId(functionId string, function any)

Exposes the function just like Expose(), but uses the given Id.

func (*Plugo) Println

func (plugo *Plugo) Println(args ...any)

func (*Plugo) Ready

func (plugo *Plugo) Ready(functionId string) error

func (*Plugo) Shutdown

func (plugo *Plugo) Shutdown()

This function gracefully shuts the plugo down. It stops listening for incoming connections and closes all existing connections.

func (*Plugo) StartChildren

func (plugo *Plugo) StartChildren(folderName string) error

func (*Plugo) Unexpose

func (plugo *Plugo) Unexpose(functionId string)

This function unexposes the function with the given functionId.