runner

Documentation

Index

• type AddrTranslator
• type AttachedRunner
• type ReattachFunc
• type Runner

Types

type AddrTranslator

type AddrTranslator interface {
	// Called before connecting on any addresses received back from the plugin.
	PluginToHost(pluginNet, pluginAddr string) (hostNet string, hostAddr string, err error)

	// Called on any host process addresses before they are sent to the plugin.
	HostToPlugin(hostNet, hostAddr string) (pluginNet string, pluginAddr string, err error)
}

AddrTranslator translates addresses between the execution context of the host process and the plugin. For example, if the plugin is in a container, the file path for a Unix socket may be different between the host and the container.

It is only intended to be used by the host process.

type AttachedRunner

type AttachedRunner interface {
	// Wait should wait until the plugin stops running, whether in response to
	// an out of band signal or in response to calling Kill().
	Wait(ctx context.Context) error

	// Kill should stop the plugin and perform any cleanup required.
	Kill(ctx context.Context) error

	// ID is a unique identifier to represent the running plugin. e.g. pid or
	// container ID.
	ID() string

	AddrTranslator
}

AttachedRunner defines a limited subset of Runner's interface to represent the reduced responsibility for plugin lifecycle when attaching to an already running plugin.

type ReattachFunc

type ReattachFunc func() (AttachedRunner, error)

ReattachFunc can be passed to a client's reattach config to reattach to an already running plugin instead of starting it ourselves.

type Runner

type Runner interface {
	// Start should start the plugin and ensure any work required for servicing
	// other interface methods is done. If the context is cancelled, it should
	// only abort any attempts to _start_ the plugin. Waiting and shutdown are
	// handled separately.
	Start(ctx context.Context) error

	// Diagnose makes a best-effort attempt to return any debug information that
	// might help users understand why a plugin failed to start and negotiate a
	// connection.
	Diagnose(ctx context.Context) string

	// Stdout is used to negotiate the go-plugin protocol.
	Stdout() io.ReadCloser

	// Stderr is used for forwarding plugin logs to the host process logger.
	Stderr() io.ReadCloser

	// Name is a human-friendly name for the plugin, such as the path to the
	// executable. It does not have to be unique.
	Name() string

	AttachedRunner
}

Runner defines the interface required by go-plugin to manage the lifecycle of of a plugin and attempt to negotiate a connection with it. Note that this is orthogonal to the protocol and transport used, which is negotiated over stdout.