README
¶
pie 
import "github.com/natefinch/pie"
package pie provides a toolkit for creating plugins for Go applications.
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.
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 ¶
- func NewConsumer() *rpc.Client
- func NewConsumerCodec(f func(io.ReadWriteCloser) rpc.ClientCodec) *rpc.Client
- func StartProvider(output io.Writer, path string, args ...string) (*rpc.Client, error)
- func StartProviderCodec(f func(io.ReadWriteCloser) rpc.ClientCodec, output io.Writer, path string, ...) (*rpc.Client, error)
- type Server
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewConsumer ¶
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.
package main
import (
"net/rpc/jsonrpc"
"github.com/natefinch/pie"
)
func main() {
client := pie.NewConsumerCodec(jsonrpc.NewClientCodec)
var reply string
client.Call("Foo.ToUpper", "something", &reply)
}
Output:
func StartProvider ¶
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.
package main
import (
"log"
"os"
"net/rpc/jsonrpc"
"github.com/natefinch/pie"
)
func main() {
client, err := pie.StartProviderCodec(jsonrpc.NewClientCodec, os.Stderr, "/var/lib/foo")
if err != nil {
log.Fatalf("failed to load foo plugin: %s", err)
}
var reply string
client.Call("Foo.ToUpper", "something", &reply)
}
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 ¶
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 ¶
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 ¶
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 ¶
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. |