plugin

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Jan 6, 2016 License: MPL-2.0 Imports: 19 Imported by: 0

Documentation

Overview

The plugin package exposes functions and helpers for communicating to plugins which are implemented as standalone binary applications.

plugin.Client fully manages the lifecycle of executing the application, connecting to it, and returning the RPC client and service names for connecting to it using the otto/rpc package.

plugin.Serve fully manages listeners to expose an RPC server from a binary that plugin.Client can connect to.

Index

Constants

View Source
const APIVersion = "1"

The APIVersion is outputted along with the RPC address. The plugin client validates this API version and will show an error if it doesn't know how to speak it.

View Source
const MagicCookieKey = "OTTO_PLUGIN_MAGIC_COOKIE"

The "magic cookie" is used to verify that the user intended to actually run this binary. If this cookie isn't present as an environmental variable, then we bail out early with an error.

View Source
const MagicCookieValue = "11aab7ff21cb9ff7b0e9975d53f17a8dab571eac9b5ff0191730046698f07b7f"

Variables

View Source
var Killed = false

If this is true, then the "unexpected EOF" panic will not be raised throughout the clients.

Functions

func CleanupClients

func CleanupClients()

This makes sure all the managed subprocesses are killed and properly logged. This should be called before the parent process running the plugins exits.

This must only be called _once_.

func Discover

func Discover(glob, dir string) ([]string, error)

Discover discovers plugins that are in a given directory.

The directory doesn't need to be absolute. For example, "." will work fine.

This currently assumes any file matching the glob is a plugin. In the future this may be smarter about checking that a file is executable and so on.

TODO: test

func Serve

func Serve(opts *ServeOpts)

Serve serves the plugins given by ServeOpts.

Serve doesn't return until the plugin is done being executed. Any errors will be outputted to the log.

func ServeMux

func ServeMux(m ServeMuxMap)

ServeMux is like Serve, but serves multiple types of plugins determined by the argument given on the command-line.

This command doesn't return until the plugin is done being executed. Any errors are logged or output to stderr.

Types

type Client

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

Client handles the lifecycle of a plugin application, determining its RPC address, and returning various types of interface implementations across the multi-process communication layer.

func NewClient

func NewClient(config *ClientConfig) (c *Client)

Creates a new plugin client which manages the lifecycle of an external plugin and gets the address for the RPC connection.

The client must be cleaned up at some point by calling Kill(). If the client is a managed client (created with NewManagedClient) you can just call CleanupClients at the end of your program and they will be properly cleaned.

func (*Client) Client

func (c *Client) Client() (*pluginrpc.Client, error)

Client returns an RPC client for the plugin.

Subsequent calls to this will return the same RPC client.

func (*Client) Exited

func (c *Client) Exited() bool

Tells whether or not the underlying process has exited.

func (*Client) Kill

func (c *Client) Kill()

End the executing subprocess (if it is running) and perform any cleanup tasks necessary such as capturing any remaining logs and so on.

This method blocks until the process successfully exits.

This method can safely be called multiple times.

func (*Client) Start

func (c *Client) Start() (addr net.Addr, err error)

Starts the underlying subprocess, communicating with it to negotiate a port for RPC connections, and returning the address to connect via RPC.

This method is safe to call multiple times. Subsequent calls have no effect. Once a client has been started once, it cannot be started again, even if it was killed.

type ClientConfig

type ClientConfig struct {
	// The unstarted subprocess for starting the plugin.
	Cmd *exec.Cmd

	// Managed represents if the client should be managed by the
	// plugin package or not. If true, then by calling CleanupClients,
	// it will automatically be cleaned up. Otherwise, the client
	// user is fully responsible for making sure to Kill all plugin
	// clients. By default the client is _not_ managed.
	Managed bool

	// The minimum and maximum port to use for communicating with
	// the subprocess. If not set, this defaults to 10,000 and 25,000
	// respectively.
	MinPort, MaxPort uint

	// StartTimeout is the timeout to wait for the plugin to say it
	// has started successfully.
	StartTimeout time.Duration

	// If non-nil, then the stderr of the client will be written to here
	// (as well as the log). This is the original os.Stderr of the subprocess.
	// This isn't the output of synced stderr.
	Stderr io.Writer

	// SyncStdout, SyncStderr can be set to override the
	// respective os.Std* values in the plugin. Care should be taken to
	// avoid races here. If these are nil, then this will automatically be
	// hooked up to os.Stdin, Stdout, and Stderr, respectively.
	//
	// If the default values (nil) are used, then this package will not
	// sync any of these streams.
	SyncStdout io.Writer
	SyncStderr io.Writer
}

ClientConfig is the configuration used to initialize a new plugin client. After being used to initialize a plugin client, that configuration must not be modified again.

type ServeMuxMap

type ServeMuxMap map[string]*ServeOpts

ServeMuxMap is the type that is used to configure ServeMux

type ServeOpts

type ServeOpts struct {
	AppFunc pluginrpc.AppFunc
}

ServeOpts configures what sorts of plugins are served.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL