github.com/mutagen-io/mutagen@v0.18.0-rc1/pkg/agent/transport.go

package agent

import (
	"fmt"
	"os"
	"os/exec"
	"strings"
	"unicode/utf8"
)

// 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.
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)
}

// run is a utility method that invokes a command via a transport, waits for it
// to complete, and returns its exit error. If there is an error creating the
// command, it will be returned wrapped, but otherwise the result of the run
// method will be returned un-wrapped, so it can be treated as an
// os/exec.ExitError.
func run(transport Transport, command string) error {
	// Create the process.
	process, err := transport.Command(command)
	if err != nil {
		return fmt.Errorf("unable to create command: %w", err)
	}

	// Run the command. We use the Output method as opposed to the Run method
	// because the former will collect standard error output that can be useful
	// in formulating an error message for the purposes of debugging.
	_, err = process.Output()

	// If there was an error, then attempt to convert it to a more useful error
	// that includes standard error output from the remote.
	if err != nil {
		exitErr, ok := err.(*exec.ExitError)
		if ok && utf8.Valid(exitErr.Stderr) {
			remoteError := strings.TrimSuffix(string(exitErr.Stderr), "\n")
			if len(remoteError) > 0 {
				return fmt.Errorf("remote error: %s", remoteError)
			}
		}
		return err
	}

	// Success.
	return nil
}

// output is a utility method that invokes a command via a transport, waits for
// it to complete, and returns its standard output and exit error. If there is
// an error creating the command, it will be returned wrapped, but otherwise the
// result of the run method will be returned un-wrapped, so it can be treated as
// an os/exec.ExitError.
func output(transport Transport, command string) ([]byte, error) {
	// Create the process.
	process, err := transport.Command(command)
	if err != nil {
		return nil, fmt.Errorf("unable to create command: %w", err)
	}

	// Run the process.
	return process.Output()
}