This section discusses the internals of how go-plugin works.
go-plugin operates by either serving a plugin or being a client connecting to a remote plugin. The "client" is the host process or the process that itself uses plugins. The "server" is the plugin process.
For a server:
- Output handshake to stdout
- Wait for connection on control address
- Serve plugins over control address
For a client:
- Launch a plugin binary
- Read and verify handshake from plugin stdout
- Connect to plugin control address using desired protocol
- Dispense plugins using control connection
The handshake is the initial communication between a plugin and a host process to determine how the host process can connect and communicate to the plugin. This handshake is done over the plugin process's stdout.
go-plugin library itself handles the handshake when using the
Server to serve a plugin. You do not need to understand the internals
of the handshake, unless you're building a go-plugin compatible plugin
in another language.
The handshake is a single line of data terminated with a newline character
\n. It looks like the following:
The structure is:
CORE-PROTOCOL-VERSION | APP-PROTOCOL-VERSION | NETWORK-TYPE | NETWORK-ADDR | PROTOCOL
CORE-PROTOCOL-VERSIONis the protocol version for go-plugin itself. The current value is
1. Please use this value. Any other value will cause your plugin to not load.
APP-PROTOCOL-VERSIONis the protocol version for the application data. This is determined by the application. You must reference the documentation for your application to determine the desired value.
NETWORK-ADDRare the networking information for connecting to this plugin. The type must be "unix" or "tcp". The address is a path to the Unix socket for "unix" and an IP address for "tcp".
PROTOCOLis the named protocol that the connection will use. If this is omitted (older versions), this is "netrpc" for Go net/rpc. This can also be "grpc". This is the protocol that the plugin wants to speak to the host process with.
When serving a plugin over TCP, the following environment variables can be specified to restrict the port that will be assigned to be from within a specific range. If not values are provided, the port will be randomly assigned by the operating system.
PLUGIN_MIN_PORT: Specifies the minimum port value that will be assigned to
PLUGIN_MAX_PORT: Specifies the maximum port value that will be assigned to