ssh

type SSHClient interface {
	// Create creates a new SSH client
	Create(user, host, keyPath string) (SSHClient, error)

	// StartTunnel starts an SSH tunnel with port forwarding from local to remote
	// It returns a function to stop the tunnel and an error if the tunnel fails to start
	StartTunnel(ctx context.Context, localPort, remotePort string) (stop func() error, err error)

	// OpenTunnel establishes an SSH tunnel forwarding remotePort to an
	// automatically chosen free local port, retrying on transient connection
	// errors. It returns the tunnel info (including the local port and a stop
	// function) and an error if the tunnel cannot be established.
	OpenTunnel(ctx context.Context, remotePort string) (*TunnelInfo, error)

	// Exec executes a command on the remote host
	Exec(ctx context.Context, cmd string) (string, error)

	// ExecCapture executes a command on the remote host and returns stdout and stderr separately
	ExecCapture(ctx context.Context, cmd string) (stdout, stderr string, err error)

	// ExecFatal executes a command and returns error if it fails
	ExecFatal(ctx context.Context, cmd string) string

	// Uploads a local file to the remote host
	Upload(ctx context.Context, localPath, remotePath string) error

	// UploadPrivate uploads like Upload but sets remotePerm on the remote path via SFTP after create and before copying payload (reduces permission race on secrets).
	UploadPrivate(ctx context.Context, localPath, remotePath string, remotePerm os.FileMode) error

	// Close closes the SSH connection
	Close() error
}

type TunnelInfo struct {
	LocalPort  int
	RemotePort int
	StopFunc   func() error
}