agent

Documentation

Overview

Package agent provides facilities for extracting, installing, and connecting to agent binaries.

Index

• Constants
• func Dial(transport Transport, prompter, root, session string, version session.Version, ...) (session.Endpoint, error)
• func Install() error
• type BundleLocation
• type Transport

Constants

const (
	// ModeInstall is the agent command to invoke for installation.
	ModeInstall = "install"
	// ModeEndpoint is the agent command to invoke for running as an endpoint.
	ModeEndpoint = "endpoint"
	// ModeVersion is the agent command to invoke to print version information.
	ModeVersion = "version"
	// ModeLegal is the agent command to invoke to print legal information.
	ModeLegal = "legal"
)

const (
	// BaseName is the base name for agent executables (sans any
	// platform-specific suffix like ".exe").
	BaseName = "mutagen-agent"
)

const (
	// BundleName is the base name of the agent bundle.
	BundleName = "mutagen-agents.tar.gz"
)

Functions

func Dial

func Dial(
	transport Transport,
	prompter,
	root,
	session string,
	version session.Version,
	configuration *session.Configuration,
	alpha bool,
) (session.Endpoint, error)

Dial connects to an agent-based endpoint using the specified transport, prompter, and endpoint metadata.

func Install

func Install() error

Install installs the current binary to the appropriate location for an agent binary with the current Mutagen version.

Types

type BundleLocation

type BundleLocation uint8

BundleLocation encodes an expected location for the agent bundle.

const (
	// BundleLocationSameDirectory specifies that the Mutagen executable in
	// which the agent package resides should expect to find the agent bundle in
	// the same directory as said executable.
	BundleLocationSameDirectory BundleLocation = iota
	// BundleLocationBuildDirectory specifies that the Mutagen executable in
	// which the agent package resides should expect to find the agent bundle in
	// the Mutagen build directory. This mode should only be used during
	// testing.
	BundleLocationBuildDirectory
)

var ExpectedBundleLocation BundleLocation

ExpectedBundleLocation specifies the expected agent bundle location. It is set by the time that init functions have completed. After that, it should only be set at the process entry point, before any code calls into the agent package.

type Transport

type Transport interface {
	// Copy copies the specified local file (which is guaranteed to exist and be
	// a file) to the remote. The provided local path will be absolute. The
	// remote path will be a filename (i.e. without path separators) that should
	// be treated as being relative to the user's home directory.
	Copy(localPath, remoteName string) error
	// Command creates (but does not start) a process that will invoke the
	// specified command on the specified remote. It should not re-direct any of
	// the output streams of the process. The command on the remote must be
	// invoked with the user's home directory as the working directory. Any
	// command provided to this interface is guaranteed to be lexable by simply
	// splitting on spaces.
	Command(command string) (*exec.Cmd, error)
	// ClassifyError is used to determine how the agent dialing infrastructure
	// should attempt to handle failure when launching agents. It is provided
	// with the process exit state as well as a string containing the standard
	// error output from the command. It should return a bool representing
	// whether or not the error condition represents a failure due to an agent
	// either not being installed or being installed improperly and a bool
	// representing whether or not the remote system should be treated as a
	// cmd.exe-like environment on Windows. If neither of these can be
	// determined reliably, this method should return an error to abort dialing.
	// If the second bool changes the dialer's platform hypothesis, it will
	// attempt to reconnect using the correct command syntax for that platform.
	// Otherwise, if the first bool indicates that the agent binary simply needs
	// to be (re-)installed, it will attempt to do so and then reconnect.
	ClassifyError(processState *os.ProcessState, errorOutput string) (bool, bool, error)
}

Transport is the interface that protocols wishing to use the agent infrastructure must implement. It should be natural for "SSH"-like protocols, i.e. those where SCP-like and SSH-like operations can be performed. Transport instances do not need to be safe for concurrent invocation unless being used for concurrent Dial operations.