train 0.12.1

data/lib/train/extras/os_detect_windows.rb

@@ -0,0 +1,57 @@
+# encoding: utf-8
+# author: Dominik Richter
+# author: Christoph Hartmann
+#
+# This is heavily based on:
+#
+#   OHAI https://github.com/chef/ohai
+#   by Adam Jacob, Chef Software Inc
+#
+module Train::Extras
+  module DetectWindows
+    def detect_windows
+      res = @backend.run_command('cmd /c ver')
+      return false if res.exit_status != 0 or res.stdout.empty?
+
+      # if the ver contains `Windows`, we know its a Windows system
+      version = res.stdout.strip
+      return false unless version.downcase =~ /windows/
+      @platform[:family] = 'windows'
+
+      # try to extract release from eg. `Microsoft Windows [Version 6.3.9600]`
+      release = /\[(?<name>.*)\]/.match(version)
+      unless release[:name].nil?
+        # release is 6.3.9600 now
+        @platform[:release] = release[:name].downcase.gsub('version', '').strip
+        # fallback, if we are not able to extract the name from wmic later
+        @platform[:name] = "Windows #{@platform[:release]}"
+      end
+
+      # try to use wmic, but lets keep it optional
+      read_wmic
+
+      true
+    end
+
+    # reads os name and version from wmic
+    # @see https://msdn.microsoft.com/en-us/library/bb742610.aspx#EEAA
+    # Thanks to Matt Wrock (https://github.com/mwrock) for this hint
+    def read_wmic
+      res = @backend.run_command('wmic os get * /format:list')
+      if res.exit_status == 0
+        sys_info = {}
+        res.stdout.lines.each { |line|
+          m = /^\s*([^=]*?)\s*=\s*(.*?)\s*$/.match(line)
+          sys_info[m[1].to_sym] = m[2] unless m.nil? || m[1].nil?
+        }
+
+        @platform[:release] = sys_info[:Version]
+        # additional info on windows
+        @platform[:build] = sys_info[:BuildNumber]
+        @platform[:name] = sys_info[:Caption]
+        @platform[:name] = @platform[:name].gsub('Microsoft', '').strip unless @platform[:name].empty?
+        @platform[:arch] = sys_info[:OSArchitecture]
+      end
+    end
+  end
+end

data/lib/train/extras/stat.rb

@@ -0,0 +1,133 @@
+# encoding: utf-8
+# author: Dominik Richter
+# author: Christoph Hartmann
+
+module Train::Extras
+  class Stat
+    TYPES = {
+      socket:           00140000,
+      symlink:          00120000,
+      file:             00100000,
+      block_device:     00060000,
+      directory:        00040000,
+      character_device: 00020000,
+      pipe:             00010000,
+    }.freeze
+
+    def self.find_type(mode)
+      res = TYPES.find { |_, mask| mask & mode == mask }
+      res.nil? ? :unknown : res[0]
+    end
+
+    def self.stat(shell_escaped_path, backend, follow_symlink)
+      # use perl scripts for aix and solaris 10
+      if backend.os.aix? || (backend.os.solaris? && backend.os[:release].to_i < 11) || backend.os.hpux?
+        return aix_stat(shell_escaped_path, backend, follow_symlink)
+      end
+      return bsd_stat(shell_escaped_path, backend, follow_symlink) if backend.os.bsd?
+      # linux and solaris 11 will use standard linux stats
+      return linux_stat(shell_escaped_path, backend, follow_symlink) if backend.os.unix?
+      # all other cases we don't handle
+      # TODO: print an error if we get here, as it shouldn't be invoked
+      # on non-unix
+      {}
+    end
+
+    def self.linux_stat(shell_escaped_path, backend, follow_symlink)
+      lstat = follow_symlink ? ' -L' : ''
+      res = backend.run_command("stat#{lstat} #{shell_escaped_path} 2>/dev/null --printf '%s\n%f\n%U\n%u\n%G\n%g\n%X\n%Y\n%C'")
+
+      # ignore the exit_code: it is != 0 if selinux labels are not supported
+      # on the system.
+
+      fields = res.stdout.split("\n")
+      return {} if fields.length != 9
+
+      tmask = fields[1].to_i(16)
+      selinux = fields[8]
+      selinux = nil if selinux == '?' or selinux == '(null)'
+
+      {
+        type:  find_type(tmask),
+        mode:  tmask & 07777,
+        owner: fields[2],
+        uid:   fields[3].to_i,
+        group: fields[4],
+        gid:   fields[5].to_i,
+        mtime: fields[7].to_i,
+        size:  fields[0].to_i,
+        selinux_label: selinux,
+      }
+    end
+
+    def self.bsd_stat(shell_escaped_path, backend, follow_symlink)
+      # From stat man page on FreeBSD:
+      # z       The size of file in bytes (st_size).
+      # p       File type and permissions (st_mode).
+      # u, g    User ID and group ID of file's owner (st_uid, st_gid).
+      # a, m, c, B
+      #         The time file was last accessed or modified, or when the
+      #         inode was last changed, or the birth time of the inode
+      #         (st_atime, st_mtime, st_ctime, st_birthtime).
+      #
+      # The special output specifier S may be used to indicate that the
+      # output, if applicable, should be in string format.  May be used
+      # in combination with:
+      #      ...
+      #      gu      Display group or user name.
+      lstat = follow_symlink ? ' -L' : ''
+      res = backend.run_command(
+        "stat#{lstat} -f '%z\n%p\n%Su\n%u\n%Sg\n%g\n%a\n%m' "\
+        "#{shell_escaped_path}")
+
+      return {} if res.exit_status != 0
+
+      fields = res.stdout.split("\n")
+      return {} if fields.length != 8
+
+      tmask = fields[1].to_i(8)
+
+      {
+        type:  find_type(tmask),
+        mode:  tmask & 07777,
+        owner: fields[2],
+        uid:   fields[3].to_i,
+        group: fields[4],
+        gid:   fields[5].to_i,
+        mtime: fields[7].to_i,
+        size:  fields[0].to_i,
+        selinux_label: fields[8],
+      }
+    end
+
+    def self.aix_stat(shell_escaped_path, backend, follow_symlink)
+      # Perl here b/c it is default on AIX
+      lstat = follow_symlink ? 'lstat' : 'stat'
+      stat_cmd = <<-EOP
+      perl -e '
+      @a = #{lstat}(shift) or exit 2;
+      $u = getpwuid($a[4]);
+      $g = getgrgid($a[5]);
+      printf("0%o\\n%s\\n%d\\n%s\\n%d\\n%d\\n%d\\n", $a[2], $u, $a[4], $u, $a[5], $a[9], $a[7])
+      ' #{shell_escaped_path}
+      EOP
+
+      res = backend.run_command(stat_cmd)
+      return {} if res.exit_status != 0
+      fields = res.stdout.split("\n")
+      return {} if fields.length != 7
+      tmask  = fields[0].to_i(8)
+      {
+        type:  find_type(tmask),
+        mode:  tmask & 07777,
+        owner: fields[1],
+        uid:   fields[2].to_i,
+        group: fields[3],
+        gid:   fields[4].to_i,
+        mtime: fields[5].to_i,
+        size:  fields[6].to_i,
+        selinux_label: nil,
+      }
+    end
+  end
+end

data/lib/train/options.rb

@@ -0,0 +1,80 @@
+# encoding: utf-8
+#
+# Author:: Dominik Richter (<dominik.richter@gmail.com>)
+# Author:: Christoph Hartmann (<chris@lollyrock.com>)
+
+module Train
+  module Options
+    def self.attach(target)
+      target.class.method(:include).call(ClassOptions)
+      target.method(:include).call(InstanceOptions)
+    end
+
+    module ClassOptions
+      def option(name, conf = nil, &block)
+        d = conf || {}
+        unless d.is_a? Hash
+          fail Train::ClientError,
+               "The transport plugin #{self} declared an option #{name} "\
+               "and didn't provide a valid configuration hash."
+        end
+
+        if !conf.nil? and !conf[:default].nil? and block_given?
+          fail Train::ClientError,
+               "The transport plugin #{self} declared an option #{name} "\
+               'with both a default value and block. Only use one of these.'
+        end
+
+        d[:default] = block if block_given?
+
+        default_options[name] = d
+      end
+
+      def default_options
+        @default_options = {} unless defined? @default_options
+        @default_options
+      end
+
+      def include_options(other)
+        unless other.respond_to?(:default_options)
+          fail "Trying to include options from module #{other.inspect}, "\
+               "which doesn't seem to support options."
+        end
+        default_options.merge!(other.default_options)
+      end
+    end
+
+    module InstanceOptions
+      # @return [Hash] options, which created this Transport
+      attr_reader :options
+
+      def default_options
+        self.class.default_options
+      end
+
+      def merge_options(base, opts)
+        res = base.merge(opts || {})
+        default_options.each do |field, hm|
+          next unless res[field].nil? and hm.key?(:default)
+          default = hm[:default]
+          if default.is_a? Proc
+            res[field] = default.call(res)
+          else
+            res[field] = default
+          end
+        end
+        res
+      end
+
+      def validate_options(opts)
+        default_options.each do |field, hm|
+          if opts[field].nil? and hm[:required]
+            fail Train::ClientError,
+                 "You must provide a value for #{field.to_s.inspect}."
+          end
+        end
+        opts
+      end
+    end
+  end
+end

data/lib/train/plugins.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+#
+# Author:: Dominik Richter (<dominik.richter@gmail.com>)
+# Author:: Christoph Hartmann (<chris@lollyrock.com>)
+
+require 'train/errors'
+
+module Train
+  class Plugins
+    autoload :Transport, 'train/plugins/transport'
+
+    class << self
+      # Retrieve the current plugin registry, containing all plugin names
+      # and their transport handlers.
+      #
+      # @return [Hash] map with plugin names and plugins
+      def registry
+        @registry ||= {}
+      end
+    end
+  end
+
+  # 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
+  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
+end

data/lib/train/plugins/base_connection.rb

@@ -0,0 +1,86 @@
+# encoding: utf-8
+#
+# Author:: Salim Afiune (<salim@afiunemaya.com.mx>)
+# Author:: Fletcher Nichol (<fnichol@nichol.ca>)
+# Author:: Dominik Richter (<dominik.richter@gmail.com>)
+
+require 'train/errors'
+require 'train/extras'
+require 'logger'
+
+class Train::Plugins::Transport
+  # 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>
+  class BaseConnection
+    include Train::Extras
+
+    # Create a new Connection instance.
+    #
+    # @param options [Hash] connection options
+    # @yield [self] yields itself for block-style invocation
+    def initialize(options = nil)
+      @options = options || {}
+      @logger = @options.delete(:logger) || Logger.new(STDOUT)
+    end
+
+    # Closes the session connection, if it is still active.
+    def close
+      # this method may be left unimplemented if that is applicable
+    end
+
+    # Execute a command using this connection.
+    #
+    # @param command [String] command string to execute
+    # @return [CommandResult] contains the result of running the command
+    def run_command(_command)
+      fail Train::ClientError, "#{self.class} does not implement #run_command()"
+    end
+
+    # Get information on the operating system which this transport connects to.
+    #
+    # @return [OSCommon] operating system information
+    def os
+      fail Train::ClientError, "#{self.class} does not implement #os()"
+    end
+
+    # Interact with files on the target. Read, write, and get metadata
+    # from files via the transport.
+    #
+    # @param [String] path which is being inspected
+    # @return [FileCommon] file object that allows for interaction
+    def file(_path, *_args)
+      fail Train::ClientError, "#{self.class} does not implement #file(...)"
+    end
+
+    # Builds a LoginCommand which can be used to open an interactive
+    # session on the remote host.
+    #
+    # @return [LoginCommand] array of command line tokens
+    def login_command
+      fail Train::ClientError, "#{self.class} does not implement #run_command()"
+    end
+
+    # 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.
+    def wait_until_ready
+      # this method may be left unimplemented if that is applicablelog
+    end
+
+    private
+
+    # @return [Logger] logger for reporting information
+    # @api private
+    attr_reader :logger
+
+    # @return [Hash] connection options
+    # @api private
+    attr_reader :options
+  end
+end

data/lib/train/plugins/transport.rb

@@ -0,0 +1,49 @@
+# encoding: utf-8
+#
+# Author:: Dominik Richter (<dominik.richter@gmail.com>)
+# Author:: Christoph Hartmann (<chris@lollyrock.com>)
+
+require 'logger'
+require 'train/errors'
+require 'train/extras'
+require 'train/options'
+
+class Train::Plugins
+  class Transport
+    include Train::Extras
+    Train::Options.attach(self)
+
+    autoload :BaseConnection, 'train/plugins/base_connection'
+
+    # Initialize a new Transport object
+    #
+    # @param [Hash] config = nil the configuration for this transport
+    # @return [Transport] the transport object
+    def initialize(options = {})
+      @options = merge_options({}, options || {})
+      @logger = @options[:logger] || Logger.new(STDOUT)
+    end
+
+    # Create a connection to the target. Options may be provided
+    # for additional configuration.
+    #
+    # @param [Hash] _options = nil provide optional configuration params
+    # @return [Connection] the connection for this configuration
+    def connection(_options = nil)
+      fail Train::ClientError, "#{self.class} does not implement #connect()"
+    end
+
+    # Register the inheriting class with as a train plugin using the
+    # provided name.
+    #
+    # @param [String] name of the plugin, by which it will be found
+    def self.name(name)
+      Train::Plugins.registry[name] = self
+    end
+
+    private
+
+    # @return [Logger] logger for reporting information
+    attr_reader :logger
+  end
+end