README

pie GoDoc Codeship Status for natefinch/pie

import "github.com/natefinch/pie"

package pie provides a toolkit for creating plugins for Go applications.

pie

Why is it called pie?

Because if you pronounce API like "a pie", then all this consuming and serving of APIs becomes a lot more palatable. Also, pies are the ultimate pluggable interface - depending on what's inside, you can get dinner, dessert, a snack, or even breakfast. Plus, then I get to say that plugins in Go are as easy as... well, you know.

If you have to explain it to your boss, just say it's an acronym for Plug In Executables. (but it's not, really)

About Pie

Plugins using this toolkit and the applications managing those plugins communicate via RPC over the plugin application's Stdin and Stdout.

Functions in this package with the prefix New are intended to be used by the plugin to set up its end of the communication. Functions in this package with the prefix Start are intended to be used by the main application to set up its end of the communication and start a plugin executable.

This package provides two conceptually different types of plugins, based on which side of the communication is the server and which is the client. Plugins which provide an API server for the main application to call are called Providers. Plugins which consume an API provided by the main application are called Consumers.

The default codec for RPC for this package is Go's gob encoding, however you may provide your own codec, such as JSON-RPC provided by net/rpc/jsonrpc.

There is no requirement that plugins for applications using this toolkit be written in Go. As long as the plugin application can consume or provide an RPC API of the correct codec, it can interoperate with main applications using this process. For example, if your main application uses JSON-RPC, many languages are capable of producing an executable that can provide a JSON-RPC API for your application to use.

Included in this repo are some simple examples of a master process and a plugin process, to see how the library can be used. An example of the standard plugin that provides an API the master process consumes is in the examples/provider directory. master_provider expects plugin_provider to be in the same directory or in your $PATH. You can just go install both of them, and it'll work correctly.

In addition to a regular plugin that provides an API, this package can be used for plugins that consume an API provided by the main process. To see an example of this, look in the examples/consumer folder.

func NewConsumer

func NewConsumer() *rpc.Client

NewConsumer returns an rpc.Client that will consume an API from the host process over this application's Stdin and Stdout using gob encoding.

func NewConsumerCodec

func NewConsumerCodec(f func(io.ReadWriteCloser) rpc.ClientCodec) *rpc.Client

NewConsumerCodec returns an rpc.Client that will consume an API from the host process over this application's Stdin and Stdout using the ClientCodec returned by f.

func StartProvider

func StartProvider(output io.Writer, path string, args ...string) (*rpc.Client, error)

StartProvider start a provider-style plugin application at the given path and args, and returns an RPC client that communicates with the plugin using gob encoding over the plugin's Stdin and Stdout. The writer passed to output will receive output from the plugin's stderr. Closing the RPC client returned from this function will shut down the plugin application.

func StartProviderCodec

func StartProviderCodec(
    f func(io.ReadWriteCloser) rpc.ClientCodec,
    output io.Writer,
    path string,
    args ...string,
) (*rpc.Client, error)

StartProviderCodec starts a provider-style plugin application at the given path and args, and returns an RPC client that communicates with the plugin using the ClientCodec returned by f over the plugin's Stdin and Stdout. The writer passed to output will receive output from the plugin's stderr. Closing the RPC client returned from this function will shut down the plugin application.

type Server

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

Server is a type that represents an RPC server that serves an API over stdin/stdout.

func NewProvider
func NewProvider() Server

NewProvider returns a Server that will serve RPC over this application's Stdin and Stdout. This method is intended to be run by the plugin application.

func StartConsumer
func StartConsumer(output io.Writer, path string, args ...string) (Server, error)

StartConsumer starts a consumer-style plugin application with the given path and args, writing its stderr to output. The plugin consumes an API this application provides. The function returns the Server for this host application, which should be used to register APIs for the plugin to consume.

func (Server) Close
func (s Server) Close() error

Close closes the connection with the client. If the client is a plugin process, the process will be stopped. Further communication using this Server will fail.

func (Server) Register
func (s Server) Register(rcvr interface{}) error

Register publishes in the provider the set of methods of the receiver value that satisfy the following conditions:

- exported method
- two arguments, both of exported type
- the second argument is a pointer
- one return value, of type error

It returns an error if the receiver is not an exported type or has no suitable methods. It also logs the error using package log. The client accesses each method using a string of the form "Type.Method", where Type is the receiver's concrete type.

func (Server) RegisterName
func (s Server) RegisterName(name string, rcvr interface{}) error

RegisterName is like Register but uses the provided name for the type instead of the receiver's concrete type.

func (Server) Serve
func (s Server) Serve()

Serve starts the Server's RPC server, serving via gob encoding. This call will block until the client hangs up.

func (Server) ServeCodec
func (s Server) ServeCodec(f func(io.ReadWriteCloser) rpc.ServerCodec)

ServeCodec starts the Server's RPC server, serving via the encoding returned by f. This call will block until the client hangs up.

Expand ▾ Collapse ▴

Documentation

Overview

    In addition to a regular plugin that provides an API, this package can be used for plugins that consume an API provided by the main process. To see an example of this, look in the examples/consumer folder.

    Index

    Examples

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func NewConsumer

    func NewConsumer() *rpc.Client

      NewConsumer returns an rpc.Client that will consume an API from the host process over this application's Stdin and Stdout using gob encoding.

      func NewConsumerCodec

      func NewConsumerCodec(f func(io.ReadWriteCloser) rpc.ClientCodec) *rpc.Client

        NewConsumerCodec returns an rpc.Client that will consume an API from the host process over this application's Stdin and Stdout using the ClientCodec returned by f.

        Example

          This function should be called from the plugin program that wants to consume an API from the master program.

          This example shows the plugin creating a JSON-RPC client talks to the host application.

          Output:
          
          

          func StartProvider

          func StartProvider(output io.Writer, path string, args ...string) (*rpc.Client, error)

            StartProvider start a provider-style plugin application at the given path and args, and returns an RPC client that communicates with the plugin using gob encoding over the plugin's Stdin and Stdout. The writer passed to output will receive output from the plugin's stderr. Closing the RPC client returned from this function will shut down the plugin application.

            func StartProviderCodec

            func StartProviderCodec(
            	f func(io.ReadWriteCloser) rpc.ClientCodec,
            	output io.Writer,
            	path string,
            	args ...string,
            ) (*rpc.Client, error)

              StartProviderCodec starts a provider-style plugin application at the given path and args, and returns an RPC client that communicates with the plugin using the ClientCodec returned by f over the plugin's Stdin and Stdout. The writer passed to output will receive output from the plugin's stderr. Closing the RPC client returned from this function will shut down the plugin application.

              Example

                This function should be called from the master program that wants to run plugins to extend its functionality.

                This example shows the master program starting a plugin at path "/var/lib/foo", using JSON-RPC, and writing its output to this application's Stderr. The application can then call methods on the rpc client returned using the standard rpc pattern.

                Output:
                
                

                Types

                type Server

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

                  Server is a type that represents an RPC server that serves an API over stdin/stdout.

                  func NewProvider

                  func NewProvider() Server

                    NewProvider returns a Server that will serve RPC over this application's Stdin and Stdout. This method is intended to be run by the plugin application.

                    func StartConsumer

                    func StartConsumer(output io.Writer, path string, args ...string) (Server, error)

                      StartConsumer starts a consumer-style plugin application with the given path and args, writing its stderr to output. The plugin consumes an API this application provides. The function returns the Server for this host application, which should be used to register APIs for the plugin to consume.

                      func (Server) Close

                      func (s Server) Close() error

                        Close closes the connection with the client. If the client is a plugin process, the process will be stopped. Further communication using this Server will fail.

                        func (Server) Register

                        func (s Server) Register(rcvr interface{}) error

                          Register publishes in the provider the set of methods of the receiver value that satisfy the following conditions:

                          - exported method
                          - two arguments, both of exported type
                          - the second argument is a pointer
                          - one return value, of type error
                          

                          It returns an error if the receiver is not an exported type or has no suitable methods. It also logs the error using package log. The client accesses each method using a string of the form "Type.Method", where Type is the receiver's concrete type.

                          func (Server) RegisterName

                          func (s Server) RegisterName(name string, rcvr interface{}) error

                            RegisterName is like Register but uses the provided name for the type instead of the receiver's concrete type.

                            func (Server) Serve

                            func (s Server) Serve()

                              Serve starts the Server's RPC server, serving via gob encoding. This call will block until the client hangs up.

                              func (Server) ServeCodec

                              func (s Server) ServeCodec(f func(io.ReadWriteCloser) rpc.ServerCodec)

                                ServeCodec starts the Server's RPC server, serving via the encoding returned by f. This call will block until the client hangs up.

                                Source Files

                                Directories

                                Path Synopsis
                                examples
                                consumer/master_consumer
                                Command example_host is an example of a main application that provides an API for plugins to consume.
                                Command example_host is an example of a main application that provides an API for plugins to consume.
                                consumer/plugin_consumer
                                Command example_consumer is a simple example of a consumer-type plugin.
                                Command example_consumer is a simple example of a consumer-type plugin.
                                provider/master_provider
                                Command example_master is a simple example of a master application that runs a standard provider plugin.
                                Command example_master is a simple example of a master application that runs a standard provider plugin.
                                provider/plugin_provider
                                Command example_plugin is an example of a very simple plugin.
                                Command example_plugin is an example of a very simple plugin.