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

     1  // Copyright (c) HashiCorp, Inc.
     2  // SPDX-License-Identifier: MPL-2.0
     3  
     4  package runner
     5  
     6  import (
     7  	"context"
     8  	"io"
     9  )
    10  
    11  // Runner defines the interface required by go-plugin to manage the lifecycle of
    12  // of a plugin and attempt to negotiate a connection with it. Note that this
    13  // is orthogonal to the protocol and transport used, which is negotiated over stdout.
    14  type Runner interface {
    15  	// Start should start the plugin and ensure any work required for servicing
    16  	// other interface methods is done. If the context is cancelled, it should
    17  	// only abort any attempts to _start_ the plugin. Waiting and shutdown are
    18  	// handled separately.
    19  	Start(ctx context.Context) error
    20  
    21  	// Diagnose makes a best-effort attempt to return any debug information that
    22  	// might help users understand why a plugin failed to start and negotiate a
    23  	// connection.
    24  	Diagnose(ctx context.Context) string
    25  
    26  	// Stdout is used to negotiate the go-plugin protocol.
    27  	Stdout() io.ReadCloser
    28  
    29  	// Stderr is used for forwarding plugin logs to the host process logger.
    30  	Stderr() io.ReadCloser
    31  
    32  	// Name is a human-friendly name for the plugin, such as the path to the
    33  	// executable. It does not have to be unique.
    34  	Name() string
    35  
    36  	AttachedRunner
    37  }
    38  
    39  // AttachedRunner defines a limited subset of Runner's interface to represent the
    40  // reduced responsibility for plugin lifecycle when attaching to an already running
    41  // plugin.
    42  type AttachedRunner interface {
    43  	// Wait should wait until the plugin stops running, whether in response to
    44  	// an out of band signal or in response to calling Kill().
    45  	Wait(ctx context.Context) error
    46  
    47  	// Kill should stop the plugin and perform any cleanup required.
    48  	Kill(ctx context.Context) error
    49  
    50  	// ID is a unique identifier to represent the running plugin. e.g. pid or
    51  	// container ID.
    52  	ID() string
    53  
    54  	AddrTranslator
    55  }
    56  
    57  // AddrTranslator translates addresses between the execution context of the host
    58  // process and the plugin. For example, if the plugin is in a container, the file
    59  // path for a Unix socket may be different between the host and the container.
    60  //
    61  // It is only intended to be used by the host process.
    62  type AddrTranslator interface {
    63  	// Called before connecting on any addresses received back from the plugin.
    64  	PluginToHost(pluginNet, pluginAddr string) (hostNet string, hostAddr string, err error)
    65  
    66  	// Called on any host process addresses before they are sent to the plugin.
    67  	HostToPlugin(hostNet, hostAddr string) (pluginNet string, pluginAddr string, err error)
    68  }
    69  
    70  // ReattachFunc can be passed to a client's reattach config to reattach to an
    71  // already running plugin instead of starting it ourselves.
    72  type ReattachFunc func() (AttachedRunner, error)