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

     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.
    64  
    65  ## Environment Variables
    66  
    67  When serving a plugin over TCP, the following environment variables can be
    68  specified to restrict the port that will be assigned to be from within a
    69  specific range. If not values are provided, the port will be randomly assigned
    70  by the operating system.
    71  
    72   * `PLUGIN_MIN_PORT`: Specifies the minimum port value that will be assigned to the listener.
    73   
    74   * `PLUGIN_MAX_PORT`: Specifies the maximum port value that will be assigned to the listener.