class Kitchen::Transport::Base::Connection

A Connection instance can be generated and re-generated, given new connection details such as connection port, hostname, credentials, etc. This object is responsible for carrying out the actions on the remote host such as executing commands, transferring files, etc.

@author Fletcher Nichol <fnichol@nichol.ca>

Attributes

logger[R]

@return [Kitchen::Logger] a logger @api private

options[R]

@return [Hash] connection options @api private

Public Class Methods

new(options = {}) { |self| ... } click to toggle source

Create a new Connection instance.

@param options [Hash] connection options @yield [self] yields itself for block-style invocation

# File lib/kitchen/transport/base.rb, line 97
def initialize(options = {})
  init_options(options)

  yield self if block_given?
end

Public Instance Methods

close() click to toggle source

Closes the session connection, if it is still active.

# File lib/kitchen/transport/base.rb, line 104
def close
  # this method may be left unimplemented if that is applicable
end
download(remotes, local) click to toggle source

Download remote files or directories to local host.

@param remotes [Array<String>] paths to remote files or directories @param local [String] path to local destination. If `local` is an

existing directory, `remote` will be downloaded into the directory
using its original name

@raise [TransportFailed] if the files could not all be downloaded

successfully, which may vary by implementation
# File lib/kitchen/transport/base.rb, line 180
def download(remotes, local) # rubocop:disable Lint/UnusedMethodArgument
  raise ClientError, "#{self.class}#download must be implemented"
end
execute(command) click to toggle source

Execute a command on the remote host.

@param command [String] command string to execute @raise [TransportFailed] if the command does not exit successfully,

which may vary by implementation
# File lib/kitchen/transport/base.rb, line 113
def execute(command)
  raise ClientError, "#{self.class}#execute must be implemented"
end
execute_with_retry(command, retryable_exit_codes = [], max_retries = 1, wait_time = 30) click to toggle source

Execute a command on the remote host and retry

@param command [String] command string to execute @param retryable_exit_codes [Array] Array of exit codes to retry against @param max_retries [Fixnum] maximum number of retry attempts @param wait_time [Fixnum] number of seconds to wait before retrying command @raise [TransportFailed] if the command does not exit successfully,

which may vary by implementation
# File lib/kitchen/transport/base.rb, line 125
def execute_with_retry(command, retryable_exit_codes = [], max_retries = 1, wait_time = 30)
  tries = 0
  begin
    tries += 1
    debug("Attempting to execute command - try #{tries} of #{max_retries}.")
    execute(command)
  rescue Exception => e
    if retry?(tries, max_retries, retryable_exit_codes, e)
      close
      sleep wait_time
      retry
    else
      raise e
    end
  end
end
login_command() click to toggle source

Builds a LoginCommand which can be used to open an interactive session on the remote host.

@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

# File lib/kitchen/transport/base.rb, line 158
def login_command
  raise ActionFailed, "Remote login not supported in #{self.class}."
end
retry?(current_try, max_retries, retryable_exit_codes, exception) click to toggle source
# File lib/kitchen/transport/base.rb, line 142
def retry?(current_try, max_retries, retryable_exit_codes, exception)
  if exception.is_a?(Kitchen::Transport::TransportFailed)
    return current_try <= max_retries &&
        !retryable_exit_codes.nil? &&
        retryable_exit_codes.flatten.include?(exception.exit_code)
  end

  false
end
upload(locals, remote) click to toggle source

Uploads local files or directories to remote host.

@param locals [Array<String>] paths to local files or directories @param remote [String] path to remote destination @raise [TransportFailed] if the files could not all be uploaded

successfully, which may vary by implementation
# File lib/kitchen/transport/base.rb, line 168
def upload(locals, remote) # rubocop:disable Lint/UnusedMethodArgument
  raise ClientError, "#{self.class}#upload must be implemented"
end
wait_until_ready() click to toggle source

Block and return only when the remote host is prepared and ready to execute command and upload files. The semantics and details will vary by implementation, but a round trip through the hosted service is preferred to simply waiting on a socket to become available.

# File lib/kitchen/transport/base.rb, line 189
def wait_until_ready
  # this method may be left unimplemented if that is applicable
end

Private Instance Methods

init_options(options) click to toggle source

Initialize incoming options for use by the object.

@param options [Hash] configuration options

# File lib/kitchen/transport/base.rb, line 206
def init_options(options)
  @options = options.dup
  @logger = @options.delete(:logger) || Kitchen.logger
end