r-train 0.9.1

data/lib/train/extras/stat.rb

@@ -0,0 +1,92 @@
+# 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,
+    }
+
+    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)
+      return bsd_stat(shell_escaped_path, backend) if backend.os.bsd?
+      return linux_stat(shell_escaped_path, backend) 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)
+      res = backend.run_command("stat #{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 & 00777,
+        owner: fields[2],
+        group: fields[4],
+        mtime: fields[7].to_i,
+        size: fields[0].to_i,
+        selinux_label: selinux,
+      }
+    end
+
+    def self.bsd_stat(shell_escaped_path, backend)
+      # 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.
+      res = backend.run_command(
+        "stat -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 & 00777,
+        owner: fields[2],
+        group: fields[4],
+        mtime: fields[7].to_i,
+        size: fields[0].to_i,
+        selinux_label: fields[8],
+      }
+    end
+  end
+end

data/lib/train/extras/windows_file.rb

@@ -0,0 +1,85 @@
+# encoding: utf-8
+# author: Dominik Richter
+# author: Christoph Hartmann
+
+require 'train/extras/stat'
+
+# PS C:\Users\Administrator> Get-Item -Path C:\test.txt | Select-Object -Property BaseName, FullName, IsReadOnly, Exists,
+# LinkType, Mode, VersionInfo, Owner, Archive, Hidden, ReadOnly, System |  ConvertTo-Json
+
+module Train::Extras
+  class WindowsFile < FileCommon
+    attr_reader :path
+    def initialize(backend, path)
+      @backend = backend
+      @path = path
+      @spath = Shellwords.escape(@path)
+    end
+
+    def content
+      return @content if defined?(@content)
+      @content = @backend.run_command(
+        "Get-Content(\"#{@spath}\") | Out-String").stdout
+      return @content unless @content.empty?
+      @content = nil if directory? # or size.nil? or size > 0
+      @content
+    end
+
+    def exist?
+      nil
+    end
+
+    def link_target
+      nil
+    end
+
+    def link_path
+      nil
+    end
+
+    def mounted?
+      nil
+    end
+
+    def type
+      :unknown
+    end
+
+    %w{
+      mode owner group mtime size selinux_label
+    }.each do |field|
+      define_method field.to_sym do
+        nil
+      end
+    end
+
+    def product_version
+      nil
+    end
+
+    def file_version
+      nil
+    end
+
+    def stat
+      nil
+    end
+
+    private
+
+    def attributes
+      return @attributes if defined?(@attributes)
+      @attributes = @backend.run_command(
+        "(Get-ItemProperty -Path \"#{@spath}\").attributes.ToString()").stdout.chomp.split(',')
+    end
+
+    def target_type
+      if attributes.include?('Archive')
+        return :file
+      elsif attributes.include?('Directory')
+        return :directory
+      end
+      :unknown
+    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

data/lib/train/transports/docker.rb

@@ -0,0 +1,102 @@
+# encoding: utf-8
+#
+# Author:: Dominik Richter
+# Author:: Christoph Hartmann
+
+require 'docker'
+
+module Train::Transports
+  class Docker < Train.plugin(1)
+    name 'docker'
+
+    include_options Train::Extras::CommandWrapper
+    option :host, required: true
+
+    def connection(state = {}, &block)
+      opts = merge_options(options, state || {})
+      validate_options(opts)
+
+      if @connection && @connection_options == opts
+        reuse_connection(&block)
+      else
+        create_new_connection(opts, &block)
+      end
+    end
+
+    private
+
+    # Creates a new Docker connection instance and save it for potential future
+    # reuse.
+    #
+    # @param options [Hash] connection options
+    # @return [Docker::Connection] a Docker connection instance
+    # @api private
+    def create_new_connection(options, &block)
+      if @connection
+        logger.debug("[Docker] shutting previous connection #{@connection}")
+        @connection.close
+      end
+
+      @connection_options = options
+      @connection = Connection.new(options, &block)
+    end
+
+    # Return the last saved Docker connection instance.
+    #
+    # @return [Docker::Connection] a Docker connection instance
+    # @api private
+    def reuse_connection
+      logger.debug("[Docker] reusing existing connection #{@connection}")
+      yield @connection if block_given?
+      @connection
+    end
+  end
+end
+
+class Train::Transports::Docker
+  class Connection < BaseConnection
+    def initialize(conf)
+      super(conf)
+      @id = options[:host]
+      @container = ::Docker::Container.get(@id) ||
+                   fail("Can't find Docker container #{@id}")
+      @files = {}
+      @cmd_wrapper = nil
+      @cmd_wrapper = CommandWrapper.load(self, @options)
+      self
+    end
+
+    def close
+      # nothing to do at the moment
+    end
+
+    def os
+      @os ||= OS.new(self)
+    end
+
+    def file(path)
+      @files[path] ||= LinuxFile.new(self, path)
+    end
+
+    def run_command(cmd)
+      cmd = @cmd_wrapper.run(cmd) unless @cmd_wrapper.nil?
+      stdout, stderr, exit_status = @container.exec([
+        '/bin/sh', '-c', cmd
+      ])
+      CommandResult.new(stdout.join, stderr.join, exit_status)
+    rescue ::Docker::Error::DockerError => _
+      raise
+    rescue => _
+      # @TODO: differentiate any other error
+      raise
+    end
+
+    class OS < OSCommon
+      def initialize(backend)
+        # hardcoded to unix/linux for now, until other operating systems
+        # are supported
+        super(backend, { family: 'unix' })
+      end
+    end
+  end
+end