github.com/hashicorp/go-plugin@v1.6.0/plugin.go (about)

     1  // Copyright (c) HashiCorp, Inc.
     2  // SPDX-License-Identifier: MPL-2.0
     3  
     4  // The plugin package exposes functions and helpers for communicating to
     5  // plugins which are implemented as standalone binary applications.
     6  //
     7  // plugin.Client fully manages the lifecycle of executing the application,
     8  // connecting to it, and returning the RPC client for dispensing plugins.
     9  //
    10  // plugin.Serve fully manages listeners to expose an RPC server from a binary
    11  // that plugin.Client can connect to.
    12  package plugin
    13  
    14  import (
    15  	"context"
    16  	"errors"
    17  	"net/rpc"
    18  
    19  	"google.golang.org/grpc"
    20  )
    21  
    22  // Plugin is the interface that is implemented to serve/connect to an
    23  // inteface implementation.
    24  type Plugin interface {
    25  	// Server should return the RPC server compatible struct to serve
    26  	// the methods that the Client calls over net/rpc.
    27  	Server(*MuxBroker) (interface{}, error)
    28  
    29  	// Client returns an interface implementation for the plugin you're
    30  	// serving that communicates to the server end of the plugin.
    31  	Client(*MuxBroker, *rpc.Client) (interface{}, error)
    32  }
    33  
    34  // GRPCPlugin is the interface that is implemented to serve/connect to
    35  // a plugin over gRPC.
    36  type GRPCPlugin interface {
    37  	// GRPCServer should register this plugin for serving with the
    38  	// given GRPCServer. Unlike Plugin.Server, this is only called once
    39  	// since gRPC plugins serve singletons.
    40  	GRPCServer(*GRPCBroker, *grpc.Server) error
    41  
    42  	// GRPCClient should return the interface implementation for the plugin
    43  	// you're serving via gRPC. The provided context will be canceled by
    44  	// go-plugin in the event of the plugin process exiting.
    45  	GRPCClient(context.Context, *GRPCBroker, *grpc.ClientConn) (interface{}, error)
    46  }
    47  
    48  // NetRPCUnsupportedPlugin implements Plugin but returns errors for the
    49  // Server and Client functions. This will effectively disable support for
    50  // net/rpc based plugins.
    51  //
    52  // This struct can be embedded in your struct.
    53  type NetRPCUnsupportedPlugin struct{}
    54  
    55  func (p NetRPCUnsupportedPlugin) Server(*MuxBroker) (interface{}, error) {
    56  	return nil, errors.New("net/rpc plugin protocol not supported")
    57  }
    58  
    59  func (p NetRPCUnsupportedPlugin) Client(*MuxBroker, *rpc.Client) (interface{}, error) {
    60  	return nil, errors.New("net/rpc plugin protocol not supported")
    61  }