Class: Kitchen::Transport::Base::Connection

Inherits:
Object
  • Object
show all
Includes:
Logging
Defined in:
lib/kitchen/transport/base.rb

Overview

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:

Instance Method Summary collapse

Methods included from Logging

#banner, #debug, #error, #fatal, #info, #warn

Constructor Details

#initialize(options = {}) {|self| ... } ⇒ Connection

Create a new Connection instance.

Yields:

  • (self) —

    yields itself for block-style invocation



97
98
99
100
101
 
# File 'lib/kitchen/transport/base.rb', line 97

def initialize(options = {})
  init_options(options)

  yield self if block_given?
end

Instance Method Details

#close ⇒ Object

Closes the session connection, if it is still active.



104
105
106
 
# File 'lib/kitchen/transport/base.rb', line 104

def close
  # this method may be left unimplemented if that is applicable
end

#download(remotes, local) ⇒ Object

Download remote files or directories to local host.

Raises:

  • (TransportFailed) —

    if the files could not all be downloaded successfully, which may vary by implementation



180
181
182
 
# 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) ⇒ Object

Execute a command on the remote host.

Raises:

  • (TransportFailed) —

    if the command does not exit successfully, which may vary by implementation



113
114
115
 
# 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) ⇒ Object

Execute a command on the remote host and retry

Raises:

  • (TransportFailed) —

    if the command does not exit successfully, which may vary by implementation



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# 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 ⇒ LoginCommand

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

Raises:



158
159
160
 
# File 'lib/kitchen/transport/base.rb', line 158

def 
  raise ActionFailed, "Remote login not supported in #{self.class}."
end

#retry?(current_try, max_retries, retryable_exit_codes, exception) ⇒ Boolean 



142
143
144
145
146
147
148
149
150
 
# 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) ⇒ Object

Uploads local files or directories to remote host.

Raises:

  • (TransportFailed) —

    if the files could not all be uploaded successfully, which may vary by implementation



168
169
170
 
# 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 ⇒ Object

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.



189
190
191
 
# File 'lib/kitchen/transport/base.rb', line 189

def wait_until_ready
  # this method may be left unimplemented if that is applicable
end