module Train

Author: Fletcher Nichol (<fnichol@nichol.ca>)
Author: Dominik Richter (<dominik.richter@gmail.com>)
Author: Christoph Hartmann (<chris@lollyrock.com>)

Licensed under the Apache License, Version 2.0 (the “License”);

Author: Dominik Richter (<dominik.richter@gmail.com>)
Author: Christoph Hartmann (<chris@lollyrock.com>)

Author: Dominik Richter (<dominik.richter@gmail.com>)

Constants

VERSION

Public Class Methods

create(name, *args) click to toggle source

Create a new transport instance, with the plugin indicated by the given name.

@param [String] name of the plugin @param [Array] *args list of arguments for the plugin @return [Transport] instance of the new transport or nil

# File lib/train.rb, line 17
def self.create(name, *args)
  cls = load_transport(name)
  cls.new(*args) unless cls.nil?
end

group_keys_and_keyfiles(conf) click to toggle source

# File lib/train.rb, line 101
def self.group_keys_and_keyfiles(conf)
  # in case the user specified a key-file, register it that way
  # we will clear the list of keys and put keys and key_files separately
  keys_mixed = conf[:keys]
  return if keys_mixed.nil?

  conf[:key_files] = []
  conf[:keys] = []
  keys_mixed.each do |key|
    if !key.nil? and File.file?(key)
      conf[:key_files].push(key)
    else
      conf[:keys].push(key)
    end
  end
end

load_transport(name) click to toggle source

Load the transport plugin indicated by name. If the plugin is not yet found in the plugin registry, it will be attempted to load from `train/transports/plugin_name`.

@param [String] name of the plugin @return [Train::Transport] the transport plugin

# File lib/train.rb, line 37
def self.load_transport(name)
  res = Train::Plugins.registry[name.to_s]
  return res unless res.nil?

  # if the plugin wasnt loaded yet:
  require 'train/transports/' + name.to_s
  Train::Plugins.registry[name.to_s]
rescue LoadError => _
  raise Train::UserError,
        "Can't find train plugin #{name.inspect}. Please install it first."
end

options(name) click to toggle source

Retrieve the configuration options of a transport plugin.

@param [String] name of the plugin @return [Hash] map of default options

# File lib/train.rb, line 26
def self.options(name)
  cls = load_transport(name)
  cls.default_options unless cls.nil?
end

plugin(version = 1) click to toggle source

Create a new plugin by inheriting from the class returned by this method. Create a versioned plugin by providing the transport layer plugin version to this method. It will then select the correct class to inherit from.

The plugin version determins what methods will be available to your plugin.

@param [Int] version = 1 the plugin version to use @return [Transport] the versioned transport base class

# File lib/train/plugins.rb, line 31
def self.plugin(version = 1)
  if version != 1
    fail ClientError,
         'Only understand train plugin version 1. You are trying to '\
         "initialize a train plugin #{version}, which is not supported "\
         'in the current release of train.'
  end
  ::Train::Plugins::Transport
end

target_config(config = nil) click to toggle source

Resolve target configuration in URI-scheme into all respective fields and merge with existing configuration. e.g. ssh://bob@remote => backend: ssh, user: bob, host: remote

# File lib/train.rb, line 52
def self.target_config(config = nil) # rubocop:disable Metrics/AbcSize
  conf = config.nil? ? {} : config.dup

  # symbolize keys
  conf = conf.each_with_object({}) do |(k, v), acc|
    acc[k.to_sym] = v
    acc
  end

  group_keys_and_keyfiles(conf)

  return conf if conf[:target].to_s.empty?

  # split up the target's host/scheme configuration
  uri = URI.parse(conf[:target].to_s)
  unless uri.host.nil? and uri.scheme.nil?
    conf[:backend]  ||= uri.scheme
    conf[:host]     ||= uri.host
    conf[:port]     ||= uri.port
    conf[:user]     ||= uri.user
    conf[:password] ||= uri.password
    conf[:path]     ||= uri.path
  end

  # ensure path is nil, if its empty; e.g. required to reset defaults for winrm
  conf[:path] = nil if !conf[:path].nil? && conf[:path].to_s.empty?

  # return the updated config
  conf
end

validate_backend(conf, default = :local) click to toggle source

# File lib/train.rb, line 83
def self.validate_backend(conf, default = :local)
  return default if conf.nil?
  res = conf[:backend]
  return res if !res.nil?

  if !conf[:target].nil?
    fail Train::UserError, 'Cannot determine backend from target '\
         "configuration #{conf[:target].inspect}. Valid example: ssh://192.168.0.1."
  end

  if !conf[:host].nil?
    fail Train::UserError, 'Host configured, but no backend was provided. Please '\
         'specify how you want to connect. Valid example: ssh://192.168.0.1.'
  end

  conf[:backend] = default
end