vendor/github.com/hashicorp/go-plugin/docs/internals.md

   1 # go-plugin Internals
   2
   3 This section discusses the internals of how go-plugin works.
   4
   5 go-plugin operates by either _serving_ a plugin or being a _client_
   6 connecting to a remote plugin. The "client" is the host process or the
   7 process that itself uses plugins. The "server" is the plugin process.
   8
   9 For a server:
  10
  11   1. Output handshake to stdout
  12   2. Wait for connection on control address
  13   3. Serve plugins over control address
  14
  15 For a client:
  16
  17   1. Launch a plugin binary
  18   2. Read and verify handshake from plugin stdout
  19   3. Connect to plugin control address using desired protocol
  20   4. Dispense plugins using control connection
  21
  22 ## Handshake
  23
  24 The handshake is the initial communication between a plugin and a host
  25 process to determine how the host process can connect and communicate to
  26 the plugin. This handshake is done over the plugin process's stdout.
  27
  28 The `go-plugin` library itself handles the handshake when using the
  29 `Server` to serve a plugin. **You do not need to understand the internals
  30 of the handshake,** unless you're building a go-plugin compatible plugin
  31 in another language.
  32
  33 The handshake is a single line of data terminated with a newline character
  34 `\n`. It looks like the following:
  35
  36 ```
  37 1|3|unix|/path/to/socket|grpc
  38 ```
  39
  40 The structure is:
  41
  42 ```
  43 CORE-PROTOCOL-VERSION | APP-PROTOCOL-VERSION | NETWORK-TYPE | NETWORK-ADDR | PROTOCOL
  44 ```
  45
  46 Where:
  47
  48   * `CORE-PROTOCOL-VERSION` is the protocol version for go-plugin itself.
  49     The current value is `1`. Please use this value. Any other value will
  50     cause your plugin to not load.
  51
  52   * `APP-PROTOCOL-VERSION` is the protocol version for the application data.
  53     This is determined by the application. You must reference the documentation
  54     for your application to determine the desired value.
  55
  56   * `NETWORK-TYPE` and `NETWORK-ADDR` are the networking information for
  57     connecting to this plugin. The type must be "unix" or "tcp". The address
  58     is a path to the Unix socket for "unix" and an IP address for "tcp".
  59
  60   * `PROTOCOL` is the named protocol that the connection will use. If this
  61     is omitted (older versions), this is "netrpc" for Go net/rpc. This can
  62     also be "grpc". This is the protocol that the plugin wants to speak to
  63     the host process with.