Decoupled plugin example

examples/basic/README.md

@@ -0,0 +1,14 @@
+Plugin Example
+--------------
+
+Compile this driver via:
+
+    go build .
+
+Compile the plugin itself via:
+
+    cd plugin/ && go build .
+
+You can then launch the plugin sample via:
+
+    ./basic

examples/basic/commons/greeter_interface.go

@@ -0,0 +1,62 @@
+package example
+
+import (
+	"net/rpc"
+
+	"github.com/hashicorp/go-plugin"
+)
+
+// Greeter is the interface that we're exposing as a plugin.
+type Greeter interface {
+	Greet() string
+}
+
+// Here is an implementation that talks over RPC
+type GreeterRPC struct{ client *rpc.Client }
+
+func (g *GreeterRPC) Greet() string {
+	var resp string
+	err := g.client.Call("Plugin.Greet", new(interface{}), &resp)
+	if err != nil {
+		// You usually want your interfaces to return errors. If they don't,
+		// there isn't much other choice here.
+		panic(err)
+	}
+
+	return resp
+}
+
+// Here is the RPC server that GreeterRPC talks to, conforming to
+// the requirements of net/rpc
+type GreeterRPCServer struct {
+	// This is the real implementation
+	Impl Greeter
+}
+
+func (s *GreeterRPCServer) Greet(args interface{}, resp *string) error {
+	*resp = s.Impl.Greet()
+	return nil
+}
+
+// This is the implementation of plugin.Plugin so we can serve/consume this
+//
+// This has two methods: Server must return an RPC server for this plugin
+// type. We construct a GreeterRPCServer for this.
+//
+// Client must return an implementation of our interface that communicates
+// over an RPC client. We return GreeterRPC for this.
+//
+// Ignore MuxBroker. That is used to create more multiplexed streams on our
+// plugin connection and is a more advanced use case.
+type GreeterPlugin struct {
+	// Impl Injection
+	Impl Greeter
+}
+
+func (p *GreeterPlugin) Server(*plugin.MuxBroker) (interface{}, error) {
+	return &GreeterRPCServer{Impl: p.Impl}, nil
+}
+
+func (GreeterPlugin) Client(b *plugin.MuxBroker, c *rpc.Client) (interface{}, error) {
+	return &GreeterRPC{client: c}, nil
+}

examples/basic/main.go

@@ -4,29 +4,21 @@ import (
 	"fmt"
 	"io/ioutil"
 	"log"
-	"net/rpc"
-	"os"
 	"os/exec"
 
 	"github.com/hashicorp/go-plugin"
+	"github.com/hashicorp/go-plugin/examples/basic/commons"
 )
 
 func main() {
-	// Normal a plugin will be a separate binary. We put both in one
-	// here so that it is easy to build and use this example.
-	if len(os.Args) >= 2 && os.Args[1] != "" {
-		mainPlugin()
-		return
-	}
-
 	// We don't want to see the plugin logs.
 	log.SetOutput(ioutil.Discard)
 
 	// We're a host! Start by launching the plugin process.
 	client := plugin.NewClient(&plugin.ClientConfig{
 		HandshakeConfig: handshakeConfig,
 		Plugins:         pluginMap,
-		Cmd:             exec.Command(os.Args[0], "plugin"),
+		Cmd:             exec.Command("./plugin/plugin", "plugin"),
 	})
 	defer client.Kill()
 
@@ -44,20 +36,10 @@ func main() {
 
 	// We should have a Greeter now! This feels like a normal interface
 	// implementation but is in fact over an RPC connection.
-	greeter := raw.(Greeter)
+	greeter := raw.(example.Greeter)
 	fmt.Println(greeter.Greet())
 }
 
-func mainPlugin() {
-	// We're a plugin! Serve the plugin. We set the handshake config
-	// so that the host and our plugin can verify they can talk to each other.
-	// Then we set the plugin map to say what plugins we're serving.
-	plugin.Serve(&plugin.ServeConfig{
-		HandshakeConfig: handshakeConfig,
-		Plugins:         pluginMap,
-	})
-}
-
 // handshakeConfigs are used to just do a basic handshake between
 // a plugin and host. If the handshake fails, a user friendly error is shown.
 // This prevents users from executing bad plugins or executing a plugin
@@ -70,62 +52,5 @@ var handshakeConfig = plugin.HandshakeConfig{
 
 // pluginMap is the map of plugins we can dispense.
 var pluginMap = map[string]plugin.Plugin{
-	"greeter": new(GreeterPlugin),
-}
-
-// Greeter is the interface that we're exposing as a plugin.
-type Greeter interface {
-	Greet() string
-}
-
-// Here is a real implementation of Greeter
-type GreeterHello struct{}
-
-func (GreeterHello) Greet() string { return "Hello!" }
-
-// Here is an implementation that talks over RPC
-type GreeterRPC struct{ client *rpc.Client }
-
-func (g *GreeterRPC) Greet() string {
-	var resp string
-	err := g.client.Call("Plugin.Greet", new(interface{}), &resp)
-	if err != nil {
-		// You usually want your interfaces to return errors. If they don't,
-		// there isn't much other choice here.
-		panic(err)
-	}
-
-	return resp
-}
-
-// Here is the RPC server that GreeterRPC talks to, conforming to
-// the requirements of net/rpc
-type GreeterRPCServer struct {
-	// This is the real implementation
-	Impl Greeter
-}
-
-func (s *GreeterRPCServer) Greet(args interface{}, resp *string) error {
-	*resp = s.Impl.Greet()
-	return nil
-}
-
-// This is the implementation of plugin.Plugin so we can serve/consume this
-//
-// This has two methods: Server must return an RPC server for this plugin
-// type. We construct a GreeterRPCServer for this.
-//
-// Client must return an implementation of our interface that communicates
-// over an RPC client. We return GreeterRPC for this.
-//
-// Ignore MuxBroker. That is used to create more multiplexed streams on our
-// plugin connection and is a more advanced use case.
-type GreeterPlugin struct{}
-
-func (GreeterPlugin) Server(*plugin.MuxBroker) (interface{}, error) {
-	return &GreeterRPCServer{Impl: new(GreeterHello)}, nil
-}
-
-func (GreeterPlugin) Client(b *plugin.MuxBroker, c *rpc.Client) (interface{}, error) {
-	return &GreeterRPC{client: c}, nil
+	"greeter": &example.GreeterPlugin{},
 }

examples/basic/plugin/greeter_impl.go

@@ -0,0 +1,33 @@
+package main
+
+import (
+	"github.com/hashicorp/go-plugin"
+	"github.com/hashicorp/go-plugin/examples/basic/commons"
+)
+
+// Here is a real implementation of Greeter
+type GreeterHello struct{}
+
+func (GreeterHello) Greet() string { return "Hello!" }
+
+// handshakeConfigs are used to just do a basic handshake between
+// a plugin and host. If the handshake fails, a user friendly error is shown.
+// This prevents users from executing bad plugins or executing a plugin
+// directory. It is a UX feature, not a security feature.
+var handshakeConfig = plugin.HandshakeConfig{
+	ProtocolVersion:  1,
+	MagicCookieKey:   "BASIC_PLUGIN",
+	MagicCookieValue: "hello",
+}
+
+// pluginMap is the map of plugins we can dispense.
+var pluginMap = map[string]plugin.Plugin{
+	"greeter": &example.GreeterPlugin{Impl: new(GreeterHello)},
+}
+
+func main() {
+	plugin.Serve(&plugin.ServeConfig{
+		HandshakeConfig: handshakeConfig,
+		Plugins:         pluginMap,
+	})
+}