Class: Train::Plugins::Transport::BaseConnection

Inherits:
Object
  • Object
show all
Includes:
Extras
Defined in:
lib/train/plugins/base_connection.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

Constructor Details

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

Create a new Connection instance.

Parameters:

  • options (Hash) (defaults to: nil) —

    connection options

Yields:

  • (self) —

    yields itself for block-style invocation



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
# File 'lib/train/plugins/base_connection.rb', line 22

def initialize(options = nil)
  @options = options || {}
  @logger = @options.delete(:logger) || Logger.new($stdout, level: :fatal)
  Train::Platforms::Detect::Specifications::OS.load
  Train::Platforms::Detect::Specifications::Api.load

  # default caching options
  @cache_enabled = {
    file: true,
    command: false,
    api_call: false,
  }

  @cache = {}
  @cache_enabled.each_key do |type|
    clear_cache(type)
  end
end

Instance Method Details

#cache_enabled?(type) ⇒ Boolean

Returns:

  • (Boolean) 


60
61
62
 
# File 'lib/train/plugins/base_connection.rb', line 60

def cache_enabled?(type)
  @cache_enabled[type.to_sym]
end

#cached_client(type, key) ⇒ Object

Returns cached client if caching enabled. Otherwise returns whatever is given in the block.

Examples:


def demo_client
  cached_client(:api_call, :demo_connection) do
    DemoClient.new(args)
  end
end

Parameters:

  • type (symbol) —

    one of [:api_call, :file, :command]

  • key (symbol) —

    for your cached connection



54
55
56
57
58
 
# File 'lib/train/plugins/base_connection.rb', line 54

def cached_client(type, key)
  return yield unless cache_enabled?(type)

  @cache[type][key] ||= yield
end

#close ⇒ Object

Closes the session connection, if it is still active.



80
81
82
 
# File 'lib/train/plugins/base_connection.rb', line 80

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

#disable_cache(type) ⇒ Object

Raises:



72
73
74
75
76
77
 
# File 'lib/train/plugins/base_connection.rb', line 72

def disable_cache(type)
  raise Train::UnknownCacheType, "#{type} is not a valid cache type" unless @cache_enabled.keys.include?(type.to_sym)

  @cache_enabled[type.to_sym] = false
  clear_cache(type.to_sym)
end

#enable_cache(type) ⇒ Object

Enable caching types for Train. Currently we support :api_call, :file and :command types

Raises:



66
67
68
69
70
 
# File 'lib/train/plugins/base_connection.rb', line 66

def enable_cache(type)
  raise Train::UnknownCacheType, "#{type} is not a valid cache type" unless @cache_enabled.keys.include?(type.to_sym)

  @cache_enabled[type.to_sym] = true
end

#file(path, *args) ⇒ Object

This is the main file call for all connections. This will call the private file_via_connection on the connection with optional caching



135
136
137
138
139
 
# File 'lib/train/plugins/base_connection.rb', line 135

def file(path, *args)
  return file_via_connection(path, *args) unless cache_enabled?(:file)

  @cache[:file][path] ||= file_via_connection(path, *args)
end

#force_platform!(name, platform_details = nil) ⇒ Object Also known as: direct_platform 



97
98
99
100
101
102
103
104
 
# File 'lib/train/plugins/base_connection.rb', line 97

def force_platform!(name, platform_details = nil)
  plat = Train::Platforms.name(name)
  plat.backend = self
  plat.platform = platform_details unless platform_details.nil?
  plat.find_family_hierarchy
  plat.add_platform_methods
  plat
end

#inspect ⇒ Object 



106
107
108
 
# File 'lib/train/plugins/base_connection.rb', line 106

def inspect
  "%s[%s]" % [self.class, (@options[:backend] || "Unknown")]
end

#load_json(j) ⇒ Object 



90
91
92
93
94
95
 
# File 'lib/train/plugins/base_connection.rb', line 90

def load_json(j)
  require "train/transports/mock"
  j["files"].each do |path, jf|
    @cache[:file][path] = Train::Transports::Mock::Connection::File.from_json(jf)
  end
end

#login_command ⇒ LoginCommand

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

Returns:

Raises:

  • (NotImplementedError) 


145
146
147
 
# File 'lib/train/plugins/base_connection.rb', line 145

def 
  raise NotImplementedError, "#{self.class} does not implement #login_command()"
end

#platform ⇒ Platform Also known as: os

Get information on the operating system which this transport connects to.

Returns:

  • (Platform) —

    system information



115
116
117
 
# File 'lib/train/plugins/base_connection.rb', line 115

def platform
  @platform ||= Train::Platforms::Detect.scan(self)
end

#run_command(cmd, &data_handler) ⇒ Object

This is the main command call for all connections. This will call the private run_command_via_connection on the connection with optional caching

This command accepts an optional data handler block. When provided, inbound data will be published vi ‘data_handler.call(data)`. This can allow callers to receive and render updates from remote command execution.



127
128
129
130
131
 
# File 'lib/train/plugins/base_connection.rb', line 127

def run_command(cmd, &data_handler)
  return run_command_via_connection(cmd, &data_handler) unless cache_enabled?(:command)

  @cache[:command][cmd] ||= run_command_via_connection(cmd, &data_handler)
end

#to_json ⇒ Object 



84
85
86
87
88
 
# File 'lib/train/plugins/base_connection.rb', line 84

def to_json
  {
    "files" => Hash[@cache[:file].map { |x, y| [x, y.to_json] }],
  }
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.



154
155
156
 
# File 'lib/train/plugins/base_connection.rb', line 154

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