agent

Documentation

Overview

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

Index

• Constants
• func ClientHandshake(connection net.Conn) error
• func Dial(logger *logging.Logger, transport Transport, mode, prompter string) (net.Conn, error)
• func ExecutableForPlatform(goos, goarch, outputPath string) (string, error)
• func Install() error
• func ServerHandshake(connection net.Conn) error
• type BundleLocation
• type Transport

Constants

const (
	// ModeInstall is the agent command to invoke for installation.
	ModeInstall = "install"
	// ModeSynchronizer is the agent command to invoke for running as a
	// synchronizer.
	ModeSynchronizer = "synchronizer"
	// ModeForwarder is the agent command to invoke for running as a forwarder.
	ModeForwarder = "forwarder"
	// 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 ClientHandshake

func ClientHandshake(connection net.Conn) error

ClientHandshake performs a client-side handshake on the connection.

func Dial

func Dial(logger *logging.Logger, transport Transport, mode, prompter string) (net.Conn, error)

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

func ExecutableForPlatform

func ExecutableForPlatform(goos, goarch, outputPath string) (string, error)

ExecutableForPlatform attempts to locate the agent bundle and extract an agent executable for the specified target platform. If no output path is specified, then the extracted file will be in a temporary location accessible to only the user, will have an appropriate extension for the target platform, and will have the executability bit set if it makes sense. The path to the extracted file will be returned, and the caller is responsible for cleaning up the file if this function returns a nil error.

func Install

func Install() error

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

func ServerHandshake

func ServerHandshake(connection net.Conn) error

ServerHandshake performs a server-side handshake on the connection.

Types

type BundleLocation

type BundleLocation uint8

BundleLocation encodes an expected location for the agent bundle.

const (
	// BundleLocationDefault indicates that the ExecutableForPlatform function
	// should expect to find the agent bundle in the same directory as the
	// current executable or (if the current executable resides in the "bin"
	// directory of a Filesystem Hierarchy Standard layout) in the libexec
	// directory.
	BundleLocationDefault BundleLocation = iota
	// BundleLocationBuildDirectory indicates that the ExecutableForPlatform
	// function should expect to find the agent bundle in the Mutagen build
	// directory. This mode is only used during integration testing. It is
	// required because test executables will be built in temporary directories.
	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 standard agent transport interface, allowing the agent dialing structure to invoke commands on the remote, copy files to the remote, and classify errors from the remote. Transport interfaces do not need to be safe for concurrent invocation unless being used for concurrent Dial operations.