vagrant 1.5.0 → 2.4.4

data/lib/vagrant/plugin/state_file.rb

@@ -0,0 +1,136 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+require "json"
+require "fileutils"
+require "tempfile"
+
+module Vagrant
+  module Plugin
+    # This is a helper to deal with the plugin state file that Vagrant
+    # uses to track what plugins are installed and activated and such.
+    class StateFile
+
+      # @return [Pathname] path to file
+      attr_reader :path
+
+      def initialize(path)
+        @path = path
+
+        @data = {}
+        if @path.exist?
+          begin
+            @data = JSON.parse(@path.read)
+          rescue JSON::ParserError => e
+            raise Vagrant::Errors::PluginStateFileParseError,
+              path: path, message: e.message
+          end
+
+          upgrade_v0! if !@data["version"]
+        end
+
+        @data["version"] ||= "1"
+        @data["installed"] ||= {}
+      end
+
+      # Add a plugin that is installed to the state file.
+      #
+      # @param [String] name The name of the plugin
+      def add_plugin(name, **opts)
+        @data["installed"][name] = {
+          "ruby_version"          => RUBY_VERSION,
+          "vagrant_version"       => Vagrant::VERSION,
+          "gem_version"           => opts[:version] || "",
+          "require"               => opts[:require] || "",
+          "sources"               => opts[:sources] || [],
+          "installed_gem_version" => opts[:installed_gem_version],
+          "env_local"             => !!opts[:env_local]
+        }
+
+        save!
+      end
+
+      # Adds a RubyGems index source to look up gems.
+      #
+      # @param [String] url URL of the source.
+      def add_source(url)
+        @data["sources"] ||= []
+        @data["sources"] << url if !@data["sources"].include?(url)
+        save!
+      end
+
+      # This returns a hash of installed plugins according to the state
+      # file. Note that this may _not_ directly match over to actually
+      # installed gems.
+      #
+      # @return [Hash]
+      def installed_plugins
+        @data["installed"]
+      end
+
+      # Returns true/false if the plugin is present in this state file.
+      #
+      # @return [Boolean]
+      def has_plugin?(name)
+        @data["installed"].key?(name)
+      end
+
+      # Remove a plugin that is installed from the state file.
+      #
+      # @param [String] name The name of the plugin.
+      def remove_plugin(name)
+        @data["installed"].delete(name)
+        save!
+      end
+
+      # Remove a source for RubyGems.
+      #
+      # @param [String] url URL of the source
+      def remove_source(url)
+        @data["sources"] ||= []
+        @data["sources"].delete(url)
+        save!
+      end
+
+      # Returns the list of RubyGems sources that will be searched for
+      # plugins.
+      #
+      # @return [Array<String>]
+      def sources
+        @data["sources"] || []
+      end
+
+      # This saves the state back into the state file.
+      def save!
+        Tempfile.open(@path.basename.to_s, @path.dirname.to_s) do |f|
+          f.binmode
+          f.write(JSON.dump(@data))
+          f.fsync
+          f.chmod(0644)
+          f.close
+          FileUtils.mv(f.path, @path)
+        end
+      end
+
+      protected
+
+      # This upgrades the internal data representation from V0 (the initial
+      # version) to V1.
+      def upgrade_v0!
+        @data["version"] = "1"
+
+        new_installed = {}
+        (@data["installed"] || []).each do |plugin|
+          new_installed[plugin] = {
+            "ruby_version"    => "0",
+            "vagrant_version" => "0",
+          }
+        end
+
+        @data["installed"] = new_installed
+
+        save!
+      end
+    end
+  end
+end

data/lib/vagrant/plugin/v1/command.rb

@@ -0,0 +1,171 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+require 'log4r'
+require "vagrant/util/safe_puts"
+
+module Vagrant
+  module Plugin
+    module V1
+      # This is the base class for a CLI command.
+      class Command
+        include Util::SafePuts
+
+        def initialize(argv, env)
+          @argv = argv
+          @env  = env
+          @logger = Log4r::Logger.new("vagrant::command::#{self.class.to_s.downcase}")
+        end
+
+        # This is what is called on the class to actually execute it. Any
+        # subclasses should implement this method and do any option parsing
+        # and validation here.
+        def execute
+        end
+
+        protected
+
+        # Parses the options given an OptionParser instance.
+        #
+        # This is a convenience method that properly handles duping the
+        # originally argv array so that it is not destroyed.
+        #
+        # This method will also automatically detect "-h" and "--help"
+        # and print help. And if any invalid options are detected, the help
+        # will be printed, as well.
+        #
+        # If this method returns `nil`, then you should assume that help
+        # was printed and parsing failed.
+        def parse_options(opts=nil)
+          # Creating a shallow copy of the arguments so the OptionParser
+          # doesn't destroy the originals.
+          argv = @argv.dup
+
+          # Default opts to a blank optionparser if none is given
+          opts ||= OptionParser.new
+
+          # Add the help option, which must be on every command.
+          opts.on_tail("-h", "--help", "Print this help") do
+            safe_puts(opts.help)
+            return nil
+          end
+
+          opts.parse!(argv)
+          return argv
+        rescue OptionParser::InvalidOption
+          raise Errors::CLIInvalidOptions, help: opts.help.chomp
+        end
+
+        # Yields a VM for each target VM for the command.
+        #
+        # This is a convenience method for easily implementing methods that
+        # take a target VM (in the case of multi-VM) or every VM if no
+        # specific VM name is specified.
+        #
+        # @param [String] name The name of the VM. Nil if every VM.
+        # @param [Boolean] single_target If true, then an exception will be
+        #   raised if more than one target is found.
+        def with_target_vms(names=nil, options=nil)
+          # Using VMs requires a Vagrant environment to be properly setup
+          raise Errors::NoEnvironmentError if !@env.root_path
+
+          # Setup the options hash
+          options ||= {}
+
+          # Require that names be an array
+          names ||= []
+          names = [names] if !names.is_a?(Array)
+
+          # First determine the proper array of VMs.
+          vms = []
+          if names.length > 0
+            names.each do |name|
+              if pattern = name[/^\/(.+?)\/$/, 1]
+                # This is a regular expression name, so we convert to a regular
+                # expression and allow that sort of matching.
+                regex = Regexp.new(pattern)
+
+                @env.vms.each do |name, vm|
+                  vms << vm if name =~ regex
+                end
+
+                raise Errors::VMNoMatchError if vms.empty?
+              else
+                # String name, just look for a specific VM
+                vms << @env.vms[name.to_sym]
+                raise Errors::VMNotFoundError, name: name if !vms[0]
+              end
+            end
+          else
+            vms = @env.vms_ordered
+          end
+
+          # Make sure we're only working with one VM if single target
+          if options[:single_target] && vms.length != 1
+            vm = @env.primary_vm
+            raise Errors::MultiVMTargetRequired if !vm
+            vms = [vm]
+          end
+
+          # If we asked for reversed ordering, then reverse it
+          vms.reverse! if options[:reverse]
+
+          # Go through each VM and yield it!
+          vms.each do |old_vm|
+            # We get a new VM from the environment here to avoid potentially
+            # stale VMs (if there was a config reload on the environment
+            # or something).
+            vm = @env.vms[old_vm.name]
+            yield vm
+          end
+        end
+
+        # This method will split the argv given into three parts: the
+        # flags to this command, the subcommand, and the flags to the
+        # subcommand. For example:
+        #
+        #     -v status -h -v
+        #
+        # The above would yield 3 parts:
+        #
+        #     ["-v"]
+        #     "status"
+        #     ["-h", "-v"]
+        #
+        # These parts are useful because the first is a list of arguments
+        # given to the current command, the second is a subcommand, and the
+        # third are the commands given to the subcommand.
+        #
+        # @return [Array] The three parts.
+        def split_main_and_subcommand(argv)
+          # Initialize return variables
+          main_args   = nil
+          sub_command = nil
+          sub_args    = []
+
+          # We split the arguments into two: One set containing any
+          # flags before a word, and then the rest. The rest are what
+          # get actually sent on to the subcommand.
+          argv.each_index do |i|
+            if !argv[i].start_with?("-")
+              # We found the beginning of the sub command. Split the
+              # args up.
+              main_args   = argv[0, i]
+              sub_command = argv[i]
+              sub_args    = argv[i + 1, argv.length - i + 1]
+
+              # Break so we don't find the next non flag and shift our
+              # main args.
+              break
+            end
+          end
+
+          # Handle the case that argv was empty or didn't contain any subcommand
+          main_args = argv.dup if main_args.nil?
+
+          return [main_args, sub_command, sub_args]
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/plugin/v1/communicator.rb

@@ -0,0 +1,101 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module Vagrant
+  module Plugin
+    module V1
+      # Base class for a communicator in Vagrant. A communicator is
+      # responsible for communicating with a machine in some way. There
+      # are various stages of Vagrant that require things such as uploading
+      # files to the machine, executing shell commands, etc. Implementors
+      # of this class are expected to provide this functionality in some
+      # way.
+      #
+      # Note that a communicator must provide **all** of the methods
+      # in this base class. There is currently no way for one communicator
+      # to provide say a more efficient way of uploading a file, but not
+      # provide shell execution. This sort of thing will come in a future
+      # version.
+      class Communicator
+        # This returns true/false depending on if the given machine
+        # can be communicated with using this communicator. If this returns
+        # `true`, then this class will be used as the primary communication
+        # method for the machine.
+        #
+        # @return [Boolean]
+        def self.match?(machine)
+          false
+        end
+
+        # Initializes the communicator with the machine that we will be
+        # communicating with. This base method does nothing (it doesn't
+        # even store the machine in an instance variable for you), so you're
+        # expected to override this and do something with the machine if
+        # you care about it.
+        #
+        # @param [Machine] machine The machine this instance is expected to
+        #   communicate with.
+        def initialize(machine)
+        end
+
+        # Checks if the target machine is ready for communication. If this
+        # returns true, then all the other methods for communicating with
+        # the machine are expected to be functional.
+        #
+        # @return [Boolean]
+        def ready?
+          false
+        end
+
+        # Download a file from the remote machine to the local machine.
+        #
+        # @param [String] from Path of the file on the remote machine.
+        # @param [String] to Path of where to save the file locally.
+        def download(from, to)
+        end
+
+        # Upload a file to the remote machine.
+        #
+        # @param [String] from Path of the file locally to upload.
+        # @param [String] to Path of where to save the file on the remote
+        #   machine.
+        def upload(from, to)
+        end
+
+        # Execute a command on the remote machine. The exact semantics
+        # of this method are up to the implementor, but in general the
+        # users of this class will expect this to be a shell.
+        #
+        # This method gives you no way to write data back to the remote
+        # machine, so only execute commands that don't expect input.
+        #
+        # @param [String] command Command to execute.
+        # @yield [type, data] Realtime output of the command being executed.
+        # @yieldparam [String] type Type of the output. This can be
+        #   `:stdout`, `:stderr`, etc. The exact types are up to the
+        #   implementor.
+        # @yieldparam [String] data Data for the given output.
+        # @return [Integer] Exit code of the command.
+        def execute(command, opts=nil)
+        end
+
+        # Executes a command on the remote machine with administrative
+        # privileges. See {#execute} for documentation, as the API is the
+        # same.
+        #
+        # @see #execute
+        def sudo(command, opts=nil)
+        end
+
+        # Executes a command and returns true if the command succeeded,
+        # and false otherwise. By default, this executes as a normal user,
+        # and it is up to the communicator implementation if they expose an
+        # option for running tests as an administrator.
+        #
+        # @see #execute
+        def test(command, opts=nil)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/plugin/v1/config.rb

@@ -0,0 +1,115 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module Vagrant
+  module Plugin
+    module V1
+      # This is the base class for a configuration key defined for
+      # V1. Any configuration key plugins for V1 should inherit from this
+      # class.
+      class Config
+        # This constant represents an unset value. This is useful so it is
+        # possible to know the difference between a configuration value that
+        # was never set, and a value that is nil (explicitly). Best practice
+        # is to initialize all variables to this value, then the {#merge}
+        # method below will "just work" in many cases.
+        UNSET_VALUE = Object.new
+
+        # This is called as a last-minute hook that allows the configuration
+        # object to finalize itself before it will be put into use. This is
+        # a useful place to do some defaults in the case the user didn't
+        # configure something or so on.
+        #
+        # An example of where this sort of thing is used or has been used:
+        # the "vm" configuration key uses this to make sure that at least
+        # one sub-VM has been defined: the default VM.
+        #
+        # The configuration object is expected to mutate itself.
+        def finalize!
+          # Default implementation is to do nothing.
+        end
+
+        # Merge another configuration object into this one. This assumes that
+        # the other object is the same class as this one. This should not
+        # mutate this object, but instead should return a new, merged object.
+        #
+        # The default implementation will simply iterate over the instance
+        # variables and merge them together, with this object overriding
+        # any conflicting instance variables of the older object. Instance
+        # variables starting with "__" (double underscores) will be ignored.
+        # This lets you set some sort of instance-specific state on your
+        # configuration keys without them being merged together later.
+        #
+        # @param [Object] other The other configuration object to merge from,
+        #   this must be the same type of object as this one.
+        # @return [Object] The merged object.
+        def merge(other)
+          result = self.class.new
+
+          # Set all of our instance variables on the new class
+          [self, other].each do |obj|
+            obj.instance_variables.each do |key|
+              # Ignore keys that start with a double underscore. This allows
+              # configuration classes to still hold around internal state
+              # that isn't propagated.
+              if !key.to_s.start_with?("@__")
+                result.instance_variable_set(key, obj.instance_variable_get(key))
+              end
+            end
+          end
+
+          result
+        end
+
+        # Allows setting options from a hash. By default this simply calls
+        # the `#{key}=` method on the config class with the value, which is
+        # the expected behavior most of the time.
+        #
+        # This is expected to mutate itself.
+        #
+        # @param [Hash] options A hash of options to set on this configuration
+        #   key.
+        def set_options(options)
+          options.each do |key, value|
+            send("#{key}=", value)
+          end
+        end
+
+        # Converts this configuration object to JSON.
+        def to_json(*a)
+          instance_variables_hash.to_json(*a)
+        end
+
+        # Returns the instance variables as a hash of key-value pairs.
+        def instance_variables_hash
+          instance_variables.inject({}) do |acc, iv|
+            acc[iv.to_s[1..-1]] = instance_variable_get(iv)
+            acc
+          end
+        end
+
+        # This is called to upgrade this V1 config to V2. The parameter given
+        # is the full V2 configuration object, so you can do anything to it
+        # that you want.
+        #
+        # No return value is expected, modifications should be made directly
+        # to the new V2 object.
+        #
+        # @param [V2::Root] new
+        def upgrade(new)
+        end
+
+        # Called after the configuration is finalized and loaded to validate
+        # this object.
+        #
+        # @param [Environment] env Vagrant::Environment object of the
+        #   environment that this configuration has been loaded into. This
+        #   gives you convenient access to things like the the root path
+        #   and so on.
+        # @param [ErrorRecorder] errors
+        def validate(env, errors)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/plugin/v1/errors.rb

@@ -0,0 +1,18 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+# This file contains all the errors that the V1 plugin interface
+# may throw.
+
+module Vagrant
+  module Plugin
+    module V1
+      # Exceptions that can be thrown within the plugin interface all
+      # inherit from this parent exception.
+      class Error < StandardError; end
+
+      # This is thrown when a command name given is invalid.
+      class InvalidCommandName < Error; end
+    end
+  end
+end

data/lib/vagrant/plugin/v1/guest.rb

@@ -0,0 +1,95 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module Vagrant
+  module Plugin
+    module V1
+      # The base class for a guest. A guest represents an installed system
+      # within a machine that Vagrant manages. There are some portions of
+      # Vagrant which are OS-specific such as mounting shared folders and
+      # halting the machine, and this abstraction allows the implementation
+      # for these to be separate from the core of Vagrant.
+      class Guest
+        class BaseError < Errors::VagrantError
+          error_namespace("vagrant.guest.base")
+        end
+
+        include Vagrant::Util
+
+        # The VM which this system is tied to.
+        attr_reader :vm
+
+        # Initializes the system. Any subclasses MUST make sure this
+        # method is called on the parent. Therefore, if a subclass overrides
+        # `initialize`, then you must call `super`.
+        def initialize(vm)
+          @vm = vm
+        end
+
+        # This method is automatically called when the system is available (when
+        # Vagrant can successfully SSH into the machine) to give the system a chance
+        # to determine the distro and return a distro-specific system.
+        #
+        # If this method returns nil, then this instance is assumed to be
+        # the most specific guest implementation.
+        def distro_dispatch
+        end
+
+        # Halt the machine. This method should gracefully shut down the
+        # operating system. This method will cause `vagrant halt` and associated
+        # commands to _block_, meaning that if the machine doesn't halt
+        # in a reasonable amount of time, this method should just return.
+        #
+        # If when this method returns, the machine's state isn't "powered_off,"
+        # Vagrant will proceed to forcefully shut the machine down.
+        def halt
+          raise BaseError, _key: :unsupported_halt
+        end
+
+        # Mounts a shared folder.
+        #
+        # This method should create, mount, and properly set permissions
+        # on the shared folder. This method should also properly
+        # adhere to any configuration values such as `shared_folder_uid`
+        # on `config.vm`.
+        #
+        # @param [String] name The name of the shared folder.
+        # @param [String] guestpath The path on the machine which the user
+        #   wants the folder mounted.
+        # @param [Hash] options Additional options for the shared folder
+        #   which can be honored.
+        def mount_shared_folder(name, guestpath, options)
+          raise BaseError, _key: :unsupported_shared_folder
+        end
+
+        # Mounts a shared folder via NFS. This assumes that the exports
+        # via the host are already done.
+        def mount_nfs(ip, folders)
+          raise BaseError, _key: :unsupported_nfs
+        end
+
+        # Configures the given list of networks on the virtual machine.
+        #
+        # The networks parameter will be an array of hashes where the hashes
+        # represent the configuration of a network interface. The structure
+        # of the hash will be roughly the following:
+        #
+        # {
+        #   type:      :static,
+        #   ip:        "192.168.33.10",
+        #   netmask:   "255.255.255.0",
+        #   interface: 1
+        # }
+        #
+        def configure_networks(networks)
+          raise BaseError, _key: :unsupported_configure_networks
+        end
+
+        # Called to change the hostname of the virtual machine.
+        def change_host_name(name)
+          raise BaseError, _key: :unsupported_host_name
+        end
+      end
+    end
+  end
+end