test-kitchen 1.3.1 → 1.4.0.beta.1

data/lib/kitchen/driver.rb

@@ -21,7 +21,7 @@ require "thor/util"
 module Kitchen
 
   # A driver is responsible for carrying out the lifecycle activities of an
-  # instance, such as creating, converging, and destroying an instance.
+  # instance, such as creating and destroying an instance.
   #
   # @author Fletcher Nichol <fnichol@nichol.ca>
   module Driver

data/lib/kitchen/driver/base.rb

@@ -16,8 +16,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "thor/util"
-
 require "kitchen/lazy_hash"
 
 module Kitchen
@@ -29,7 +27,6 @@ module Kitchen
     # @author Fletcher Nichol <fnichol@nichol.ca>
     class Base
 
-      include ShellOut
       include Configurable
       include Logging
 
@@ -41,13 +38,6 @@ module Kitchen
         init_config(config)
       end
 
-      # Returns the name of this driver, suitable for display in a CLI.
-      #
-      # @return [String] name of this driver
-      def name
-        self.class.name.split("::").last
-      end
-
       # Creates an instance.
       #
       # @param state [Hash] mutable instance and driver state
@@ -55,27 +45,6 @@ module Kitchen
       def create(state) # rubocop:disable Lint/UnusedMethodArgument
       end
 
-      # Converges a running instance.
-      #
-      # @param state [Hash] mutable instance and driver state
-      # @raise [ActionFailed] if the action could not be completed
-      def converge(state) # rubocop:disable Lint/UnusedMethodArgument
-      end
-
-      # Sets up an instance.
-      #
-      # @param state [Hash] mutable instance and driver state
-      # @raise [ActionFailed] if the action could not be completed
-      def setup(state) # rubocop:disable Lint/UnusedMethodArgument
-      end
-
-      # Verifies a converged instance.
-      #
-      # @param state [Hash] mutable instance and driver state
-      # @raise [ActionFailed] if the action could not be completed
-      def verify(state) # rubocop:disable Lint/UnusedMethodArgument
-      end
-
       # Destroys an instance.
       #
       # @param state [Hash] mutable instance and driver state
@@ -83,26 +52,6 @@ module Kitchen
       def destroy(state) # rubocop:disable Lint/UnusedMethodArgument
       end
 
-      # Returns the shell command that will log into an instance.
-      #
-      # @param state [Hash] mutable instance and driver state
-      # @return [LoginCommand] an object containing the array of command line
-      #   tokens and exec options to be used in a fork/exec
-      # @raise [ActionFailed] if the action could not be completed
-      def login_command(state) # rubocop:disable Lint/UnusedMethodArgument
-        raise ActionFailed, "Remote login is not supported in this driver."
-      end
-
-      # Performs whatever tests that may be required to ensure that this driver
-      # will be able to function in the current environment. This may involve
-      # checking for the presence of certain directories, software installed,
-      # etc.
-      #
-      # @raise [UserError] if the driver will not be able to perform or if a
-      #   documented dependency is missing from the system
-      def verify_dependencies
-      end
-
       class << self
         # @return [Array<Symbol>] an array of action method names that cannot
         #   be run concurrently and must be run in serial via a shared mutex
@@ -128,7 +77,7 @@ module Kitchen
       # @param methods [Array<Symbol>] one or more actions as symbols
       # @raise [ClientError] if any method is not a valid action method name
       def self.no_parallel_for(*methods)
-        action_methods = [:create, :converge, :setup, :verify, :destroy]
+        action_methods = [:create, :setup, :verify, :destroy]
 
         Array(methods).each do |meth|
           next if action_methods.include?(meth)
@@ -142,13 +91,6 @@ module Kitchen
 
       private
 
-      # Returns a suitable logger to use for output.
-      #
-      # @return [Kitchen::Logger] a logger
-      def logger
-        instance ? instance.logger : Kitchen.logger
-      end
-
       # Intercepts any bare #puts calls in subclasses and issues an INFO log
       # event instead.
       #
@@ -164,30 +106,6 @@ module Kitchen
       def print(msg)
         info(msg)
       end
-
-      # Delegates to Kitchen::ShellOut.run_command, overriding some default
-      # options:
-      #
-      # * `:use_sudo` defaults to the value of `config[:use_sudo]` in the
-      #   Driver object
-      # * `:log_subject` defaults to a String representation of the Driver's
-      #   class name
-      #
-      # @see ShellOut#run_command
-      def run_command(cmd, options = {})
-        base_options = {
-          :use_sudo => config[:use_sudo],
-          :log_subject => Thor::Util.snake_case(self.class.to_s)
-        }.merge(options)
-        super(cmd, base_options)
-      end
-
-      # Returns the Busser object associated with the driver.
-      #
-      # @return [Busser] a busser
-      def busser
-        instance.busser
-      end
     end
   end
 end

data/lib/kitchen/driver/dummy.rb

@@ -39,11 +39,6 @@ module Kitchen
         report(:create, state)
       end
 
-      # (see Base#converge)
-      def converge(state)
-        report(:converge, state)
-      end
-
       # (see Base#setup)
       def setup(state)
         report(:setup, state)

data/lib/kitchen/driver/ssh_base.rb

@@ -16,56 +16,106 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "thor/util"
+
+require "kitchen/lazy_hash"
+
 module Kitchen
 
   module Driver
 
-    # Base class for a driver that uses SSH to communication with an instance.
+    # Legacy base class for a driver that uses SSH to communication with an
+    # instance. This class has been updated to use the Instance's Transport to
+    # issue commands and transfer files and no longer uses the `Kitchen:SSH`
+    # class directly.
+    #
+    # **NOTE:** Authors of new Drivers are encouraged to inherit from
+    # `Kitchen::Driver::Base` instead and existing Driver authors are
+    # encouraged to update their Driver class to inherit from
+    # `Kitchen::Driver::SSHBase`.
+    #
     # A subclass must implement the following methods:
     # * #create(state)
     # * #destroy(state)
     #
     # @author Fletcher Nichol <fnichol@nichol.ca>
-    class SSHBase < Base
+    # @deprecated While all possible effort has been made to preserve the
+    #   original behavior of this class, future improvements to the Driver,
+    #   Transport, and Verifier subsystems may not be picked up in these
+    #   Drivers. When legacy Driver::SSHBase support is removed, this class
+    #   will no longer be available.
+    class SSHBase
+
+      include ShellOut
+      include Configurable
+      include Logging
 
       default_config :sudo, true
       default_config :port, 22
 
+      # Creates a new Driver object using the provided configuration data
+      # which will be merged with any default configuration.
+      #
+      # @param config [Hash] provided driver configuration
+      def initialize(config = {})
+        init_config(config)
+      end
+
       # (see Base#create)
       def create(state) # rubocop:disable Lint/UnusedMethodArgument
         raise ClientError, "#{self.class}#create must be implemented"
       end
 
       # (see Base#converge)
-      def converge(state)
+      def converge(state) # rubocop:disable Metrics/AbcSize
         provisioner = instance.provisioner
         provisioner.create_sandbox
         sandbox_dirs = Dir.glob("#{provisioner.sandbox_path}/*")
 
-        Kitchen::SSH.new(*build_ssh_args(state)) do |conn|
-          run_remote(provisioner.install_command, conn)
-          run_remote(provisioner.init_command, conn)
-          transfer_path(sandbox_dirs, provisioner[:root_path], conn)
-          run_remote(provisioner.prepare_command, conn)
-          run_remote(provisioner.run_command, conn)
+        instance.transport.connection(backcompat_merged_state(state)) do |conn|
+          conn.execute(env_cmd(provisioner.install_command))
+          conn.execute(env_cmd(provisioner.init_command))
+          info("Transferring files to #{instance.to_str}")
+          conn.upload(sandbox_dirs, provisioner[:root_path])
+          debug("Transfer complete")
+          conn.execute(env_cmd(provisioner.prepare_command))
+          conn.execute(env_cmd(provisioner.run_command))
         end
+      rescue Kitchen::Transport::TransportFailed => ex
+        raise ActionFailed, ex.message
       ensure
-        provisioner && provisioner.cleanup_sandbox
+        instance.provisioner.cleanup_sandbox
       end
 
       # (see Base#setup)
       def setup(state)
-        Kitchen::SSH.new(*build_ssh_args(state)) do |conn|
-          run_remote(busser.setup_cmd, conn)
+        verifier = instance.verifier
+
+        instance.transport.connection(backcompat_merged_state(state)) do |conn|
+          conn.execute(env_cmd(verifier.install_command))
         end
+      rescue Kitchen::Transport::TransportFailed => ex
+        raise ActionFailed, ex.message
       end
 
       # (see Base#verify)
-      def verify(state)
-        Kitchen::SSH.new(*build_ssh_args(state)) do |conn|
-          run_remote(busser.sync_cmd, conn)
-          run_remote(busser.run_cmd, conn)
+      def verify(state) # rubocop:disable Metrics/AbcSize
+        verifier = instance.verifier
+        verifier.create_sandbox
+        sandbox_dirs = Dir.glob(File.join(verifier.sandbox_path, "*"))
+
+        instance.transport.connection(backcompat_merged_state(state)) do |conn|
+          conn.execute(env_cmd(verifier.init_command))
+          info("Transferring files to #{instance.to_str}")
+          conn.upload(sandbox_dirs, verifier[:root_path])
+          debug("Transfer complete")
+          conn.execute(env_cmd(verifier.prepare_command))
+          conn.execute(env_cmd(verifier.run_command))
         end
+      rescue Kitchen::Transport::TransportFailed => ex
+        raise ActionFailed, ex.message
+      ensure
+        instance.verifier.cleanup_sandbox
       end
 
       # (see Base#destroy)
@@ -75,7 +125,8 @@ module Kitchen
 
       # (see Base#login_command)
       def login_command(state)
-        SSH.new(*build_ssh_args(state)).login_command
+        instance.transport.connection(backcompat_merged_state(state)).
+          login_command
       end
 
       # Executes an arbitrary command on an instance over an SSH connection.
@@ -84,8 +135,8 @@ module Kitchen
       # @param command [String] the command to be executed
       # @raise [ActionFailed] if the command could not be successfully completed
       def remote_command(state, command)
-        Kitchen::SSH.new(*build_ssh_args(state)) do |conn|
-          run_remote(command, conn)
+        instance.transport.connection(backcompat_merged_state(state)) do |conn|
+          conn.execute(env_cmd(command))
         end
       end
 
@@ -96,13 +147,71 @@ module Kitchen
       # @deprecated This method should no longer be called directly and exists
       #   to support very old drivers. This will be removed in the future.
       def ssh(ssh_args, command)
-        Kitchen::SSH.new(*ssh_args) do |conn|
-          run_remote(command, conn)
+        pseudo_state = { :hostname => ssh_args[0], :username => ssh_args[1] }
+        pseudo_state.merge!(ssh_args[2])
+        connection_state = backcompat_merged_state(pseudo_state)
+
+        instance.transport.connection(connection_state) do |conn|
+          conn.execute(env_cmd(command))
+        end
+      end
+
+      # Performs whatever tests that may be required to ensure that this driver
+      # will be able to function in the current environment. This may involve
+      # checking for the presence of certain directories, software installed,
+      # etc.
+      #
+      # @raise [UserError] if the driver will not be able to perform or if a
+      #   documented dependency is missing from the system
+      def verify_dependencies
+      end
+
+      class << self
+        # @return [Array<Symbol>] an array of action method names that cannot
+        #   be run concurrently and must be run in serial via a shared mutex
+        attr_reader :serial_actions
+      end
+
+      # Registers certain driver actions that cannot be safely run concurrently
+      # in threads across multiple instances. Typically this might be used
+      # for create or destroy actions that use an underlying resource that
+      # cannot be used at the same time.
+      #
+      # A shared mutex for this driver object will be used to synchronize all
+      # registered methods.
+      #
+      # @example a single action method that cannot be run concurrently
+      #
+      #   no_parallel_for :create
+      #
+      # @example multiple action methods that cannot be run concurrently
+      #
+      #   no_parallel_for :create, :destroy
+      #
+      # @param methods [Array<Symbol>] one or more actions as symbols
+      # @raise [ClientError] if any method is not a valid action method name
+      def self.no_parallel_for(*methods)
+        action_methods = [:create, :converge, :setup, :verify, :destroy]
+
+        Array(methods).each do |meth|
+          next if action_methods.include?(meth)
+
+          raise ClientError, "##{meth} is not a valid no_parallel_for method"
         end
+
+        @serial_actions ||= []
+        @serial_actions += methods
       end
 
       private
 
+      def backcompat_merged_state(state)
+        driver_ssh_keys = %w[
+          forward_agent hostname password port ssh_key username
+        ].map(&:to_sym)
+        config.select { |key, _| driver_ssh_keys.include?(key) }.rmerge(state)
+      end
+
       # Builds arguments for constructing a `Kitchen::SSH` instance.
       #
       # @param state [Hash] state hash
@@ -131,6 +240,7 @@ module Kitchen
       # @return [String] command string
       # @api private
       def env_cmd(cmd)
+        return if cmd.nil?
         env = "env"
         env << " http_proxy=#{config[:http_proxy]}"   if config[:http_proxy]
         env << " https_proxy=#{config[:https_proxy]}" if config[:https_proxy]
@@ -177,7 +287,52 @@ module Kitchen
       # @param options [Hash] configuration hash (default: `{}`)
       # @api private
       def wait_for_sshd(hostname, username = nil, options = {})
-        SSH.new(hostname, username, { :logger => logger }.merge(options)).wait
+        pseudo_state = { :hostname => hostname }
+        pseudo_state[:username] = username if username
+        pseudo_state.merge!(options)
+
+        instance.transport.connection(backcompat_merged_state(pseudo_state)).
+          wait_until_ready
+      end
+
+      # Intercepts any bare #puts calls in subclasses and issues an INFO log
+      # event instead.
+      #
+      # @param msg [String] message string
+      def puts(msg)
+        info(msg)
+      end
+
+      # Intercepts any bare #print calls in subclasses and issues an INFO log
+      # event instead.
+      #
+      # @param msg [String] message string
+      def print(msg)
+        info(msg)
+      end
+
+      # Delegates to Kitchen::ShellOut.run_command, overriding some default
+      # options:
+      #
+      # * `:use_sudo` defaults to the value of `config[:use_sudo]` in the
+      #   Driver object
+      # * `:log_subject` defaults to a String representation of the Driver's
+      #   class name
+      #
+      # @see ShellOut#run_command
+      def run_command(cmd, options = {})
+        base_options = {
+          :use_sudo => config[:use_sudo],
+          :log_subject => Thor::Util.snake_case(self.class.to_s)
+        }.merge(options)
+        super(cmd, base_options)
+      end
+
+      # Returns the Busser object associated with the driver.
+      #
+      # @return [Busser] a busser
+      def busser
+        instance.verifier
       end
     end
   end

data/lib/kitchen/instance.rb

@@ -64,9 +64,13 @@ module Kitchen
     #   automation tools
     attr_reader :provisioner
 
-    # @return [Busser] busser object for instance to manage the busser
+    # @return [Transport::Base] transport object which will communicate with
+    #   an instance.
+    attr_reader :transport
+
+    # @return [Verifier] verifier object for instance to manage the verifier
     #   installation on this instance
-    attr_reader :busser
+    attr_reader :verifier
 
     # @return [Logger] the logger for this instance
     attr_reader :logger
@@ -78,8 +82,9 @@ module Kitchen
     # @option options [Platform] :platform the platform (**Required**)
     # @option options [Driver::Base] :driver the driver (**Required**)
     # @option options [Provisioner::Base] :provisioner the provisioner
+    # @option options [Transport::Base] :transport the transport
     #   (**Required**)
-    # @option options [Busser] :busser the busser logger (**Required**)
+    # @option options [Verifier] :verifier the verifier logger (**Required**)
     # @option options [Logger] :logger the instance logger
     #   (default: Kitchen.logger)
     # @option options [StateFile] :state_file the state file object to use
@@ -93,12 +98,15 @@ module Kitchen
       @name         = self.class.name_for(@suite, @platform)
       @driver       = options.fetch(:driver)
       @provisioner  = options.fetch(:provisioner)
-      @busser       = options.fetch(:busser)
+      @transport    = options.fetch(:transport)
+      @verifier     = options.fetch(:verifier)
       @logger       = options.fetch(:logger) { Kitchen.logger }
       @state_file   = options.fetch(:state_file)
 
       setup_driver
       setup_provisioner
+      setup_transport
+      setup_verifier
     end
 
     # Returns a displayable representation of the instance.
@@ -121,7 +129,7 @@ module Kitchen
 
     # Converges this running instance.
     #
-    # @see Driver::Base#converge
+    # @see Provisioner::Base#call
     # @return [self] this instance, used to chain actions
     #
     # @todo rescue Driver::ActionFailed and return some kind of null object
@@ -188,32 +196,37 @@ module Kitchen
     end
 
     # Logs in to this instance by invoking a system command, provided by the
-    # instance's driver. This could be an SSH command, telnet, or serial
+    # instance's transport. This could be an SSH command, telnet, or serial
     # console session.
     #
     # **Note** This method calls exec and will not return.
     #
-    # @see Driver::LoginCommand
-    # @see Driver::Base#login_command
+    # @see Kitchen::LoginCommand
+    # @see Transport::Base::Connection#login_command
     def login
       state = state_file.read
       if state[:last_action].nil?
         raise UserError, "Instance #{to_str} has not yet been created"
       end
 
-      login_command = driver.login_command(state)
-      cmd, *args = login_command.cmd_array
-      options = login_command.options
+      lc = if legacy_ssh_base_driver?
+        legacy_ssh_base_login(state)
+      else
+        transport.connection(state).login_command
+      end
 
-      debug(%{Login command: #{cmd} #{args.join(" ")} (Options: #{options})})
-      Kernel.exec(cmd, *args, options)
+      debug(%{Login command: #{lc.command} #{lc.arguments.join(" ")} } \
+        "(Options: #{lc.options})")
+      Kernel.exec(*lc.exec_args)
     end
 
     # Executes an arbitrary command on this instance.
     #
     # @param command [String] a command string to execute
     def remote_exec(command)
-      driver.remote_command(state_file.read, command)
+      transport.connection(state_file.read) do |conn|
+        conn.execute(command)
+      end
     end
 
     # Returns a Hash of configuration and other useful diagnostic information.
@@ -221,7 +234,9 @@ module Kitchen
     # @return [Hash] a diagnostic hash
     def diagnose
       result = Hash.new
-      [:state_file, :driver, :provisioner, :busser].each do |sym|
+      [
+        :platform, :state_file, :driver, :provisioner, :transport, :verifier
+      ].each do |sym|
         obj = send(sym)
         result[sym] = obj.respond_to?(:diagnose) ? obj.diagnose : :unknown
       end
@@ -250,7 +265,8 @@ module Kitchen
     # @api private
     def validate_options(options)
       [
-        :suite, :platform, :driver, :provisioner, :busser, :state_file
+        :suite, :platform, :driver, :provisioner,
+        :transport, :verifier, :state_file
       ].each do |k|
         next if options.key?(k)
 
@@ -281,6 +297,22 @@ module Kitchen
       @provisioner.finalize_config!(self)
     end
 
+    # Perform any final configuration or preparation needed for the transport
+    # object carry out its duties.
+    #
+    # @api private
+    def setup_transport
+      transport.finalize_config!(self)
+    end
+
+    # Perform any final configuration or preparation needed for the verifier
+    # object carry out its duties.
+    #
+    # @api private
+    def setup_verifier
+      verifier.finalize_config!(self)
+    end
+
     # Perform all actions in order from last state to desired state.
     #
     # @param desired [Symbol] a symbol representing the desired action state
@@ -305,11 +337,20 @@ module Kitchen
 
     # Perform the converge action.
     #
-    # @see Driver::Base#converge
+    # @see Provisioner::Base#call
     # @return [self] this instance, used to chain actions
     # @api private
     def converge_action
-      perform_action(:converge, "Converging")
+      banner "Converging #{to_str}..."
+      elapsed = action(:converge) do |state|
+        if legacy_ssh_base_driver?
+          legacy_ssh_base_converge(state)
+        else
+          provisioner.call(state)
+        end
+      end
+      info("Finished converging #{to_str} #{Util.duration(elapsed.real)}.")
+      self
     end
 
     # Perform the setup action.
@@ -318,7 +359,12 @@ module Kitchen
     # @return [self] this instance, used to chain actions
     # @api private
     def setup_action
-      perform_action(:setup, "Setting up")
+      banner "Setting up #{to_str}..."
+      elapsed = action(:setup) do |state|
+        legacy_ssh_base_setup(state) if legacy_ssh_base_driver?
+      end
+      info("Finished setting up #{to_str} #{Util.duration(elapsed.real)}.")
+      self
     end
 
     # Perform the verify action.
@@ -327,7 +373,16 @@ module Kitchen
     # @return [self] this instance, used to chain actions
     # @api private
     def verify_action
-      perform_action(:verify, "Verifying")
+      banner "Verifying #{to_str}..."
+      elapsed = action(:verify) do |state|
+        if legacy_ssh_base_driver?
+          legacy_ssh_base_verify(state)
+        else
+          verifier.call(state)
+        end
+      end
+      info("Finished verifying #{to_str} #{Util.duration(elapsed.real)}.")
+      self
     end
 
     # Perform the destroy action.
@@ -454,6 +509,71 @@ module Kitchen
       "#{what.capitalize} failed on instance #{to_str}."
     end
 
+    # Invokes `Driver#converge` on a legacy Driver, which inherits from
+    # `Kitchen::Driver::SSHBase`.
+    #
+    # @param state [Hash] mutable instance state
+    # @deprecated When legacy Driver::SSHBase support is removed, the
+    #   `#converge` method will no longer be called on the Driver.
+    # @api private
+    def legacy_ssh_base_converge(state)
+      warn("Running legacy converge for '#{driver.name}' Driver")
+      # TODO: Document upgrade path and provide link
+      # warn("Driver authors: please read http://example.com for more details.")
+      driver.converge(state)
+    end
+
+    # @return [TrueClass,FalseClass] whether or not the Driver inherits from
+    #   `Kitchen::Driver::SSHBase`
+    # @deprecated When legacy Driver::SSHBase support is removed, the
+    #   `#converge` method will no longer be called on the Driver.
+    # @api private
+    def legacy_ssh_base_driver?
+      driver.class < Kitchen::Driver::SSHBase
+    end
+
+    # Invokes `Driver#login_command` on a legacy Driver, which inherits from
+    # `Kitchen::Driver::SSHBase`.
+    #
+    # @param state [Hash] mutable instance state
+    # @deprecated When legacy Driver::SSHBase support is removed, the
+    #   `#login_command` method will no longer be called on the Driver.
+    # @api private
+    def legacy_ssh_base_login(state)
+      warn("Running legacy login for '#{driver.name}' Driver")
+      # TODO: Document upgrade path and provide link
+      # warn("Driver authors: please read http://example.com for more details.")
+      driver.login_command(state)
+    end
+
+    # Invokes `Driver#setup` on a legacy Driver, which inherits from
+    # `Kitchen::Driver::SSHBase`.
+    #
+    # @param state [Hash] mutable instance state
+    # @deprecated When legacy Driver::SSHBase support is removed, the
+    #   `#setup` method will no longer be called on the Driver.
+    # @api private
+    def legacy_ssh_base_setup(state)
+      warn("Running legacy setup for '#{driver.name}' Driver")
+      # TODO: Document upgrade path and provide link
+      # warn("Driver authors: please read http://example.com for more details.")
+      driver.setup(state)
+    end
+
+    # Invokes `Driver#verify` on a legacy Driver, which inherits from
+    # `Kitchen::Driver::SSHBase`.
+    #
+    # @param state [Hash] mutable instance state
+    # @deprecated When legacy Driver::SSHBase support is removed, the
+    #   `#verify` method will no longer be called on the Driver.
+    # @api private
+    def legacy_ssh_base_verify(state)
+      warn("Running legacy verify for '#{driver.name}' Driver")
+      # TODO: Document upgrade path and provide link
+      # warn("Driver authors: please read http://example.com for more details.")
+      driver.verify(state)
+    end
+
     # The simplest finite state machine pseudo-implementation needed to manage
     # an Instance.
     #