vagrant 1.5.0 → 2.4.4

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

@@ -0,0 +1,69 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module Vagrant
+  module Plugin
+    module V1
+      # Base class for a host in Vagrant. A host class contains functionality
+      # that is specific to a specific OS that is running Vagrant. This
+      # abstraction is done because there is some host-specific logic that
+      # Vagrant must do in some cases.
+      class Host
+        # This returns true/false depending on if the current running system
+        # matches the host class.
+        #
+        # @return [Boolean]
+        def self.match?
+          nil
+        end
+
+        # The precedence of the host when checking for matches. This is to
+        # allow certain host such as generic OS's ("Linux", "BSD", etc.)
+        # to be specified last.
+        #
+        # The hosts with the higher numbers will be checked first.
+        #
+        # If you're implementing a basic host, you can probably ignore this.
+        def self.precedence
+          5
+        end
+
+        # Initializes a new host class.
+        #
+        # The only required parameter is a UI object so that the host
+        # objects have some way to communicate with the outside world.
+        #
+        # @param [UI] ui UI for the hosts to output to.
+        def initialize(ui)
+          @ui = ui
+        end
+
+        # Returns true of false denoting whether or not this host supports
+        # NFS shared folder setup. This method ideally should verify that
+        # NFS is installed.
+        #
+        # @return [Boolean]
+        def nfs?
+          false
+        end
+
+        # Exports the given hash of folders via NFS.
+        #
+        # @param [String] id A unique ID that is guaranteed to be unique to
+        #   match these sets of folders.
+        # @param [String] ip IP of the guest machine.
+        # @param [Hash] folders Shared folders to sync.
+        def nfs_export(id, ip, folders)
+        end
+
+        # Prunes any NFS exports made by Vagrant which aren't in the set
+        # of valid ids given.
+        #
+        # @param [Array<String>] valid_ids Valid IDs that should not be
+        #   pruned.
+        def nfs_prune(valid_ids)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+require "log4r"
+
+module Vagrant
+  module Plugin
+    module V1
+      # This class maintains a list of all the registered plugins as well
+      # as provides methods that allow querying all registered components of
+      # those plugins as a single unit.
+      class Manager
+        attr_reader :registered
+
+        def initialize
+          @logger = Log4r::Logger.new("vagrant::plugin::v1::manager")
+          @registered = []
+        end
+
+        # This returns all the registered communicators.
+        #
+        # @return [Hash]
+        def communicators
+          result = {}
+
+          @registered.each do |plugin|
+            result.merge!(plugin.communicator.to_hash)
+          end
+
+          result
+        end
+
+        # This returns all the registered configuration classes.
+        #
+        # @return [Hash]
+        def config
+          result = {}
+
+          @registered.each do |plugin|
+            plugin.config.each do |key, klass|
+              result[key] = klass
+            end
+          end
+
+          result
+        end
+
+        # This returns all the registered configuration classes that were
+        # marked as "upgrade safe."
+        #
+        # @return [Hash]
+        def config_upgrade_safe
+          result = {}
+
+          @registered.each do |plugin|
+            configs = plugin.data[:config_upgrade_safe]
+            if configs
+              configs.each do |key|
+                result[key] = plugin.config.get(key)
+              end
+            end
+          end
+
+          result
+        end
+
+        # This returns all the registered guests.
+        #
+        # @return [Hash]
+        def guests
+          result = {}
+
+          @registered.each do |plugin|
+            result.merge!(plugin.guest.to_hash)
+          end
+
+          result
+        end
+
+        # This returns all registered host classes.
+        #
+        # @return [Hash]
+        def hosts
+          hosts = {}
+
+          @registered.each do |plugin|
+            hosts.merge!(plugin.host.to_hash)
+          end
+
+          hosts
+        end
+
+        # This returns all registered providers.
+        #
+        # @return [Hash]
+        def providers
+          providers = {}
+
+          @registered.each do |plugin|
+            providers.merge!(plugin.provider.to_hash)
+          end
+
+          providers
+        end
+
+        # This registers a plugin. This should _NEVER_ be called by the public
+        # and should only be called from within Vagrant. Vagrant will
+        # automatically register V1 plugins when a name is set on the
+        # plugin.
+        def register(plugin)
+          if !@registered.include?(plugin)
+            @logger.info("Registered plugin: #{plugin.name}")
+            @registered << plugin
+          end
+        end
+
+        # This clears out all the registered plugins. This is only used by
+        # unit tests and should not be called directly.
+        def reset!
+          @registered.clear
+        end
+
+        # This unregisters a plugin so that its components will no longer
+        # be used. Note that this should only be used for testing purposes.
+        def unregister(plugin)
+          if @registered.include?(plugin)
+            @logger.info("Unregistered: #{plugin.name}")
+            @registered.delete(plugin)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,231 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+require "set"
+require "log4r"
+
+module Vagrant
+  module Plugin
+    module V1
+      # This is the superclass for all V1 plugins.
+      class Plugin
+        # Special marker that can be used for action hooks that matches
+        # all action sequences.
+        ALL_ACTIONS = :__all_actions__
+
+        # The logger for this class.
+        LOGGER = Log4r::Logger.new("vagrant::plugin::v1::plugin")
+
+        # Set the root class up to be ourself, so that we can reference this
+        # from within methods which are probably in subclasses.
+        ROOT_CLASS = self
+
+        # This returns the manager for all V1 plugins.
+        #
+        # @return [V1::Manager]
+        def self.manager
+          @manager ||= Manager.new
+        end
+
+        # Set the name of the plugin. The moment that this is called, the
+        # plugin will be registered and available. Before this is called, a
+        # plugin does not exist. The name must be unique among all installed
+        # plugins.
+        #
+        # @param [String] name Name of the plugin.
+        # @return [String] The name of the plugin.
+        def self.name(name=UNSET_VALUE)
+          # Get or set the value first, so we have a name for logging when
+          # we register.
+          result = get_or_set(:name, name)
+
+          # The plugin should be registered if we're setting a real name on it
+          Plugin.manager.register(self) if name != UNSET_VALUE
+
+          # Return the result
+          result
+        end
+
+        # Sets a human-friendly description of the plugin.
+        #
+        # @param [String] value Description of the plugin.
+        # @return [String] Description of the plugin.
+        def self.description(value=UNSET_VALUE)
+          get_or_set(:description, value)
+        end
+
+        # Registers a callback to be called when a specific action sequence
+        # is run. This allows plugin authors to hook into things like VM
+        # bootup, VM provisioning, etc.
+        #
+        # @param [Symbol] name Name of the action.
+        # @return [Array] List of the hooks for the given action.
+        def self.action_hook(name, &block)
+          # Get the list of hooks for the given hook name
+          data[:action_hooks] ||= {}
+          hooks = data[:action_hooks][name.to_sym] ||= []
+
+          # Return the list if we don't have a block
+          return hooks if !block_given?
+
+          # Otherwise add the block to the list of hooks for this action.
+          hooks << block
+        end
+
+        # Defines additional command line commands available by key. The key
+        # becomes the subcommand, so if you register a command "foo" then
+        # "vagrant foo" becomes available.
+        #
+        # @param [String] name Subcommand key.
+        def self.command(name=UNSET_VALUE, &block)
+          data[:command] ||= Registry.new
+
+          if name != UNSET_VALUE
+            # Validate the name of the command
+            if name.to_s !~ /^[-a-z0-9]+$/i
+              raise InvalidCommandName, "Commands can only contain letters, numbers, and hyphens"
+            end
+
+            # Register a new command class only if a name was given.
+            data[:command].register(name.to_sym, &block)
+          end
+
+          # Return the registry
+          data[:command]
+        end
+
+        # Defines additional communicators to be available. Communicators
+        # should be returned by a block passed to this method. This is done
+        # to ensure that the class is lazy loaded, so if your class inherits
+        # from or uses any Vagrant internals specific to Vagrant 1.0, then
+        # the plugin can still be defined without breaking anything in future
+        # versions of Vagrant.
+        #
+        # @param [String] name Communicator name.
+        def self.communicator(name=UNSET_VALUE, &block)
+          data[:communicator] ||= Registry.new
+
+          # Register a new communicator class only if a name was given.
+          data[:communicator].register(name.to_sym, &block) if name != UNSET_VALUE
+
+          # Return the registry
+          data[:communicator]
+        end
+
+        # Defines additional configuration keys to be available in the
+        # Vagrantfile. The configuration class should be returned by a
+        # block passed to this method. This is done to ensure that the class
+        # is lazy loaded, so if your class inherits from any classes that
+        # are specific to Vagrant 1.0, then the plugin can still be defined
+        # without breaking anything in future versions of Vagrant.
+        #
+        # @param [String] name Configuration key.
+        # @param [Boolean] upgrade_safe If this is true, then this configuration
+        #   key is safe to load during an upgrade, meaning that it depends
+        #   on NO Vagrant internal classes. Do _not_ set this to true unless
+        #   you really know what you're doing, since you can cause Vagrant
+        #   to crash (although Vagrant will output a user-friendly error
+        #   message if this were to happen).
+        def self.config(name=UNSET_VALUE, upgrade_safe=false, &block)
+          data[:config] ||= Registry.new
+
+          # Register a new config class only if a name was given.
+          if name != UNSET_VALUE
+            data[:config].register(name.to_sym, &block)
+
+            # If we were told this is an upgrade safe configuration class
+            # then we add it to the set.
+            if upgrade_safe
+              data[:config_upgrade_safe] ||= Set.new
+              data[:config_upgrade_safe].add(name.to_sym)
+            end
+          end
+
+          # Return the registry
+          data[:config]
+        end
+
+        # Defines an additionally available guest implementation with
+        # the given key.
+        #
+        # @param [String] name Name of the guest.
+        def self.guest(name=UNSET_VALUE, &block)
+          data[:guests] ||= Registry.new
+
+          # Register a new guest class only if a name was given
+          data[:guests].register(name.to_sym, &block) if name != UNSET_VALUE
+
+          # Return the registry
+          data[:guests]
+        end
+
+        # Defines an additionally available host implementation with
+        # the given key.
+        #
+        # @param [String] name Name of the host.
+        def self.host(name=UNSET_VALUE, &block)
+          data[:hosts] ||= Registry.new
+
+          # Register a new host class only if a name was given
+          data[:hosts].register(name.to_sym, &block) if name != UNSET_VALUE
+
+          # Return the registry
+          data[:hosts]
+        end
+
+        # Registers additional providers to be available.
+        #
+        # @param [Symbol] name Name of the provider.
+        def self.provider(name=UNSET_VALUE, &block)
+          data[:providers] ||= Registry.new
+
+          # Register a new provider class only if a name was given
+          data[:providers].register(name.to_sym, &block) if name != UNSET_VALUE
+
+          # Return the registry
+          data[:providers]
+        end
+
+        # Registers additional provisioners to be available.
+        #
+        # @param [String] name Name of the provisioner.
+        def self.provisioner(name=UNSET_VALUE, &block)
+          data[:provisioners] ||= Registry.new
+
+          # Register a new provisioner class only if a name was given
+          data[:provisioners].register(name.to_sym, &block) if name != UNSET_VALUE
+
+          # Return the registry
+          data[:provisioners]
+        end
+
+        # Returns the internal data associated with this plugin. This
+        # should NOT be called by the general public.
+        #
+        # @return [Hash]
+        def self.data
+          @data ||= {}
+        end
+
+        protected
+
+        # Sentinel value denoting that a value has not been set.
+        UNSET_VALUE = Object.new
+
+        # Helper method that will set a value if a value is given, or otherwise
+        # return the already set value.
+        #
+        # @param [Symbol] key Key for the data
+        # @param [Object] value Value to store.
+        # @return [Object] Stored value.
+        def self.get_or_set(key, value=UNSET_VALUE)
+          # If no value is to be set, then return the value we have already set
+          return data[key] if value.eql?(UNSET_VALUE)
+
+          # Otherwise set the value
+          data[key] = value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module Vagrant
+  module Plugin
+    module V1
+      # This is the base class for a provider for the V1 API. A provider
+      # is responsible for creating compute resources to match the needs
+      # of a Vagrant-configured system.
+      class Provider
+        # Initialize the provider to represent the given machine.
+        #
+        # @param [Vagrant::Machine] machine The machine that this provider
+        #   is responsible for.
+        def initialize(machine)
+        end
+
+        # This should return an action callable for the given name.
+        #
+        # @param [Symbol] name Name of the action.
+        # @return [Object] A callable action sequence object, whether it
+        #   is a proc, object, etc.
+        def action(name)
+          nil
+        end
+
+        # This method is called if the underlying machine ID changes. Providers
+        # can use this method to load in new data for the actual backing
+        # machine or to realize that the machine is now gone (the ID can
+        # become `nil`). No parameters are given, since the underlying machine
+        # is simply the machine instance given to this object. And no
+        # return value is necessary.
+        def machine_id_changed
+        end
+
+        # This should return a hash of information that explains how to
+        # SSH into the machine. If the machine is not at a point where
+        # SSH is even possible, then `nil` should be returned.
+        #
+        # The general structure of this returned hash should be the
+        # following:
+        #
+        #     {
+        #       host: "1.2.3.4",
+        #       port: "22",
+        #       username: "mitchellh",
+        #       private_key_path: "/path/to/my/key"
+        #     }
+        #
+        # **Note:** Vagrant only supports private key based authentication,
+        # mainly for the reason that there is no easy way to exec into an
+        # `ssh` prompt with a password, whereas we can pass a private key
+        # via commandline.
+        #
+        # @return [Hash] SSH information. For the structure of this hash
+        #   read the accompanying documentation for this method.
+        def ssh_info
+          nil
+        end
+
+        # This should return the state of the machine within this provider.
+        # The state can be any symbol.
+        #
+        # @return [Symbol]
+        def state
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module Vagrant
+  module Plugin
+    module V1
+      # This is the base class for a provisioner for the V1 API. A provisioner
+      # is primarily responsible for installing software on a Vagrant guest.
+      class Provisioner
+        # The environment which provisioner is running in. This is the
+        # action environment, not a Vagrant::Environment.
+        attr_reader :env
+
+        # The configuration for this provisioner. This will be an instance of
+        # the `Config` class which is part of the provisioner.
+        attr_reader :config
+
+        def initialize(env, config)
+          @env    = env
+          @config = config
+        end
+
+        # This method is expected to return a class that is used for
+        # configuring the provisioner. This return value is expected to be
+        # a subclass of {Config}.
+        #
+        # @return [Config]
+        def self.config_class
+        end
+
+        # This is the method called to "prepare" the provisioner. This is called
+        # before any actions are run by the action runner (see {Vagrant::Actions::Runner}).
+        # This can be used to setup shared folders, forward ports, etc. Whatever is
+        # necessary on a "meta" level.
+        #
+        # No return value is expected.
+        def prepare
+        end
+
+        # This is the method called to provision the system. This method
+        # is expected to do whatever necessary to provision the system (create files,
+        # SSH, etc.)
+        def provision!
+        end
+
+        # This is the method called to when the system is being destroyed
+        # and allows the provisioners to engage in any cleanup tasks necessary.
+        def cleanup
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/plugin/v1.rb

@@ -0,0 +1,25 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+require "log4r"
+require "vagrant/plugin/v1/errors"
+
+module Vagrant
+  module Plugin
+    module V1
+      autoload :Command, "vagrant/plugin/v1/command"
+      autoload :Communicator, "vagrant/plugin/v1/communicator"
+      autoload :Config, "vagrant/plugin/v1/config"
+      autoload :Guest,  "vagrant/plugin/v1/guest"
+      autoload :Host,   "vagrant/plugin/v1/host"
+      autoload :Manager, "vagrant/plugin/v1/manager"
+      autoload :Plugin, "vagrant/plugin/v1/plugin"
+      autoload :Provider, "vagrant/plugin/v1/provider"
+      autoload :Provisioner, "vagrant/plugin/v1/provisioner"
+
+      # Errors
+      autoload :Error, "vagrant/plugin/v1/error"
+      autoload :InvalidCommandName, "vagrant/plugin/v1/error"
+    end
+  end
+end