vagrant 1.5.0 → 2.4.4

data/lib/vagrant/plugin/v2/plugin.rb

@@ -0,0 +1,296 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+require "set"
+require "log4r"
+require "vagrant/plugin/v2/components"
+
+module Vagrant
+  module Plugin
+    module V2
+      # This is the superclass for all V2 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::v2::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 V2 plugins.
+        #
+        # @return [V2::Manager]
+        def self.manager
+          @manager ||= local_manager
+        end
+
+        def self.local_manager
+          @_manager ||= Manager.new
+        end
+
+        # Returns the {Components} for this plugin.
+        #
+        # @return [Components]
+        def self.components
+          @components ||= Components.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 [String] name Name of the action.
+        # @param [Symbol] hook_name The location to hook. If this isn't
+        #   set, every middleware action is hooked.
+        # @return [Array] List of the hooks for the given action.
+        def self.action_hook(name, hook_name=nil, &block)
+          # The name is currently not used but we want it for the future.
+          hook_name = hook_name.to_s if hook_name
+
+          hook_name ||= ALL_ACTIONS
+          components.action_hooks[hook_name.to_sym] << 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, **opts, &block)
+          # 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
+
+          # By default, the command is primary
+          opts[:primary] = true if !opts.key?(:primary)
+
+          # Register the command
+          components.commands.register(name.to_sym) do
+            [block, opts]
+          end
+
+          nil
+        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.
+        def self.config(name, scope=nil, &block)
+          scope ||= :top
+          components.configs[scope].register(name.to_sym, &block)
+          nil
+        end
+
+        # Defines an additionally available guest implementation with
+        # the given key.
+        #
+        # @param [String] name Name of the guest.
+        # @param [String] parent Name of the parent guest (if any)
+        def self.guest(name, parent=nil, &block)
+          components.guests.register(name.to_sym) do
+            parent = parent.to_sym if parent
+
+            [block.call, parent]
+          end
+          nil
+        end
+
+        # Defines a capability for the given guest. The block should return
+        # a class/module that has a method with the capability name, ready
+        # to be executed. This means that if it is an instance method,
+        # the block should return an instance of the class.
+        #
+        # @param [String] guest The name of the guest
+        # @param [String] cap The name of the capability
+        def self.guest_capability(guest, cap, &block)
+          components.guest_capabilities[guest.to_sym].register(cap.to_sym, &block)
+          nil
+        end
+
+        # Defines an additionally available host implementation with
+        # the given key.
+        #
+        # @param [String] name Name of the host.
+        # @param [String] parent Name of the parent host (if any)
+        def self.host(name, parent=nil, &block)
+          components.hosts.register(name.to_sym) do
+            parent = parent.to_sym if parent
+
+            [block.call, parent]
+          end
+          nil
+        end
+
+        # Defines a capability for the given host. The block should return
+        # a class/module that has a method with the capability name, ready
+        # to be executed. This means that if it is an instance method,
+        # the block should return an instance of the class.
+        #
+        # @param [String] host The name of the host
+        # @param [String] cap The name of the capability
+        def self.host_capability(host, cap, &block)
+          components.host_capabilities[host.to_sym].register(cap.to_sym, &block)
+          nil
+        end
+
+        # Registers additional providers to be available.
+        #
+        # @param [Symbol] name Name of the provider.
+        def self.provider(name=UNSET_VALUE, options=nil, &block)
+          options ||= {}
+          options[:priority] ||= 5
+
+          components.providers.register(name.to_sym) do
+            [block.call, options]
+          end
+
+          nil
+        end
+
+        # Defines a capability for the given provider. The block should return
+        # a class/module that has a method with the capability name, ready
+        # to be executed. This means that if it is an instance method,
+        # the block should return an instance of the class.
+        #
+        # @param [String] provider The name of the provider
+        # @param [String] cap The name of the capability
+        def self.provider_capability(provider, cap, &block)
+          components.provider_capabilities[provider.to_sym].register(cap.to_sym, &block)
+          nil
+        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
+
+        # Registers additional pushes to be available.
+        #
+        # @param [String] name Name of the push.
+        # @param [Hash] options List of options for the push.
+        def self.push(name, options=nil, &block)
+          components.pushes.register(name.to_sym) do
+            [block.call, options]
+          end
+
+          nil
+        end
+
+        # Registers additional synced folder implementations.
+        #
+        # @param [String] name Name of the implementation.
+        # @param [Integer] priority The priority of the implementation,
+        # higher (big) numbers are tried before lower (small) numbers.
+        def self.synced_folder(name, priority=10, &block)
+          components.synced_folders.register(name.to_sym) do
+            [block.call, priority]
+          end
+
+          nil
+        end
+
+        # Defines a capability for the given synced folder. The block should return
+        # a class/module that has a method with the capability name, ready
+        # to be executed. This means that if it is an instance method,
+        # the block should return an instance of the class.
+        #
+        # @param [String] synced_folder The name of the synced folder
+        # @param [String] cap The name of the capability
+        def self.synced_folder_capability(synced_folder, cap, &block)
+          components.synced_folder_capabilities[synced_folder.to_sym].register(cap.to_sym, &block)
+          nil
+        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 = :__UNSET__VALUE__
+
+        # 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/v2/provider.rb

@@ -0,0 +1,118 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+require "vagrant/capability_host"
+
+module Vagrant
+  module Plugin
+    module V2
+      # This is the base class for a provider for the V2 API. A provider
+      # is responsible for creating compute resources to match the needs
+      # of a Vagrant-configured system.
+      class Provider
+        include CapabilityHost
+
+        # This is called early, before a machine is instantiated, to check
+        # if this provider is usable. This should return true or false.
+        #
+        # If raise_error is true, then instead of returning false, this
+        # should raise an error with a helpful message about why this
+        # provider cannot be used.
+        #
+        # @param [Boolean] raise_error If true, raise exception if not usable.
+        # @return [Boolean]
+        def self.usable?(raise_error=false)
+          # Return true by default for backwards compat since this was
+          # introduced long after providers were being written.
+          true
+        end
+
+        # This is called early, before a machine is instantiated, to check
+        # if this provider is installed. This should return true or false.
+        #
+        # If the provider is not installed and Vagrant determines it is
+        # able to install this provider, then it will do so. Installation
+        # is done by calling Environment.install_provider.
+        #
+        # If Environment.can_install_provider? returns false, then an error
+        # will be shown to the user.
+        def self.installed?
+          # By default return true for backwards compat so all providers
+          # continue to work.
+          true
+        end
+
+        # 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 must be an instance of {MachineState}. Please read the
+        # documentation of that class for more information.
+        #
+        # @return [MachineState]
+        def state
+          nil
+        end
+
+        # This is an internal initialize function that should never be
+        # overridden. It is used to initialize some common internal state
+        # that is used in a provider.
+        def _initialize(name, machine)
+          initialize_capabilities!(
+            name.to_sym,
+            { name.to_sym => [Class.new, nil] },
+            Vagrant.plugin("2").manager.provider_capabilities,
+            machine,
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module Vagrant
+  module Plugin
+    module V2
+      # This is the base class for a provisioner for the V2 API. A provisioner
+      # is primarily responsible for installing software on a Vagrant guest.
+      class Provisioner
+        attr_reader :machine
+        attr_reader :config
+
+        # Initializes the provisioner with the machine that it will be
+        # provisioning along with the provisioner configuration (if there
+        # is any).
+        #
+        # The provisioner should _not_ do anything at this point except
+        # initialize internal state.
+        #
+        # @param [Machine] machine The machine that this will be provisioning.
+        # @param [Object] config Provisioner configuration, if one was set.
+        def initialize(machine, config)
+          @machine = machine
+          @config  = config
+        end
+
+        # Called with the root configuration of the machine so the provisioner
+        # can add some configuration on top of the machine.
+        #
+        # During this step, and this step only, the provisioner should modify
+        # the root machine configuration to add any additional features it
+        # may need. Examples include sharing folders, networking, and so on.
+        # This step is guaranteed to be called before any of those steps are
+        # done so the provisioner may do that.
+        #
+        # No return value is expected.
+        def configure(root_config)
+        end
+
+        # This is the method called when the actual provisioning should be
+        # done. The communicator is guaranteed to be ready at this point,
+        # and any shared folders or networks are already setup.
+        #
+        # No return value is expected.
+        def provision
+        end
+
+        # This is the method called when destroying a machine that allows
+        # for any state related to the machine created by the provisioner
+        # to be cleaned up.
+        def cleanup
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/plugin/v2/push.rb

@@ -0,0 +1,30 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module Vagrant
+  module Plugin
+    module V2
+      class Push
+        attr_reader :env
+        attr_reader :config
+
+        # Initializes the pusher with the given environment the push
+        # configuration.
+        #
+        # @param [Environment] env
+        # @param [Object] config Push configuration
+        def initialize(env, config)
+          @env     = env
+          @config  = config
+        end
+
+        # This is the method called when the actual pushing should be
+        # done.
+        #
+        # No return value is expected.
+        def push
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/plugin/v2/synced_folder.rb

@@ -0,0 +1,113 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: BUSL-1.1
+
+module Vagrant
+  module Plugin
+    module V2
+      # This is the base class for a synced folder implementation.
+      class SyncedFolder
+        class Collection < Hash
+
+          # @return [Array<Symbol>] names of synced folder types
+          def types
+            keys
+          end
+
+          # Fetch the synced plugin folder of the given type
+          #
+          # @param [Symbol] t Synced folder type
+          # @return [Vagrant::Plugin::V2::SyncedFolder]
+          def type(t)
+            f = detect { |k, _| k.to_sym == t.to_sym }.last
+            raise KeyError, "Unknown synced folder type" if !f
+            f.values.first[:plugin]
+          end
+
+          # Converts to a regular Hash and removes
+          # plugin instances so the result is ready
+          # for serialization
+          #
+          # @return [Hash]
+          def to_h
+            c = lambda do |h|
+              h.keys.each do |k|
+                if h[k].is_a?(Hash)
+                  h[k] = c.call(h[k].to_h.clone)
+                end
+              end
+              h
+            end
+            h = c.call(super)
+            h.values.each do |f|
+              f.values.each do |g|
+                g.delete(:plugin)
+              end
+            end
+            h
+          end
+        end
+
+        include CapabilityHost
+
+        # This is called early when the synced folder is set to determine
+        # if this implementation can be used for this machine. This should
+        # return true or false.
+        #
+        # @param [Machine] machine
+        # @param [Boolean] raise_error If true, should raise an exception
+        #   if it isn't usable.
+        # @return [Boolean]
+        def usable?(machine, raise_error=false)
+        end
+
+        # DEPRECATED: This will be removed.
+        #
+        # @deprecated
+        def prepare(machine, folders, opts)
+        end
+
+        # This is called after the machine is booted and after networks
+        # are setup.
+        #
+        # This might be called with new folders while the machine is running.
+        # If so, then this should add only those folders without removing
+        # any existing ones.
+        #
+        # No return value.
+        def enable(machine, folders, opts)
+        end
+
+        # This is called to remove the synced folders from a running
+        # machine.
+        #
+        # This is not guaranteed to be called, but this should be implemented
+        # by every synced folder implementation.
+        #
+        # @param [Machine] machine The machine to modify.
+        # @param [Hash] folders The folders to remove. This will not contain
+        #   any folders that should remain.
+        # @param [Hash] opts Any options for the synced folders.
+        def disable(machine, folders, opts)
+        end
+
+        # This is called after destroying the machine during a
+        # `vagrant destroy` and also prior to syncing folders during
+        # a `vagrant up`.
+        #
+        # No return value.
+        #
+        # @param [Machine] machine
+        # @param [Hash] opts
+        def cleanup(machine, opts)
+        end
+
+        def _initialize(machine, synced_folder_type)
+          plugins = Vagrant.plugin("2").manager.synced_folders
+          capabilities = Vagrant.plugin("2").manager.synced_folder_capabilities
+          initialize_capabilities!(synced_folder_type, plugins, capabilities, machine)
+          self
+        end
+      end
+    end
+  end
+end