train 0.12.1

data/README.md

@@ -0,0 +1,156 @@
+# Train - Transport Interface
+
+Train lets you talk to your local or remote operating systems with a unified interface.
+
+It allows you to:
+
+* execute commands via `run_command`
+* interact with files via `file`
+* identify the target operating system via `os`
+
+Train supports:
+
+* Local execution
+* SSH
+* WinRM
+* Docker
+* Mock (for testing and debugging)
+
+# Examples
+
+## Setup
+
+**Local**
+
+```ruby
+require 'train'
+train = Train.create('local')
+```
+
+**SSH**
+
+```ruby
+require 'train'
+train = Train.create('ssh',
+  host: '1.2.3.4', port: 22, user: 'root', key_files: '/vagrant')
+```
+
+**WinRM**
+
+```ruby
+require 'train'
+train = Train.create('winrm',
+  host: '1.2.3.4', user: 'Administrator', password: '...', ssl: true, self_signed: true)
+```
+
+**Docker**
+
+```ruby
+require 'train'
+train = Train.create('docker', host: 'container_id...')
+```
+
+## Configuration
+
+To get a list of available options for a plugin:
+
+```ruby
+puts Train.options('ssh')
+```
+This will provide all configuration options:
+
+```ruby
+{
+  :host     => { :required => true},
+  :port     => { :default  => 22, :required => true},
+  :user     => { :default  => "root", :required => true},
+  :keys     => { :default  => nil},
+  :password => { :default  => nil},
+  ...
+```
+
+## Usage
+
+```ruby
+# start or reuse a connection
+conn = train.connection
+
+# run a command on Linux/Unix/Mac
+puts conn.run_command('whoami').stdout
+
+# get OS info
+puts conn.os[:family]
+puts conn.os[:release]
+
+# access files
+puts conn.file('/proc/version').content
+
+# close the connection
+conn.close
+```
+
+# Testing
+
+We perform `unit`, `integration` and `windows` tests.
+
+* `unit` tests ensure the intended behaviour of the implementation
+* `integration` tests run against VMs and docker containers
+* `windows` tests that run on appveyor for windows integration tests
+
+## Windows
+
+```
+# run windows tests
+bundle exec rake test:windows
+
+# run single tests
+bundle exec ruby -I .\test\windows\ .\test\windows\local_test.rb
+```
+
+
+# Kudos and Contributors
+
+Train is heavily based on the work of:
+
+* [test-kitchen](https://github.com/test-kitchen/test-kitchen)  
+
+    by [Fletcher Nichol](fnichol@nichol.ca)
+    and [a great community of contributors](https://github.com/test-kitchen/test-kitchen/graphs/contributors)
+
+* [ohai](https://github.com/chef/ohai)
+
+    by Adam Jacob, Chef Software Inc.
+    and [a great community of contributors](https://github.com/chef/ohai/graphs/contributors)
+
+
+## Contributing
+
+1. Fork it
+1. Create your feature branch (git checkout -b my-new-feature)
+1. Commit your changes (git commit -am 'Add some feature')
+1. Push to the branch (git push origin my-new-feature)
+1. Create new Pull Request
+
+## License
+
+| **Author:**          | Dominik Richter (<drichter@chef.io>)
+
+| **Author:**          | Christoph Hartmann (<chartmann@chef.io>)
+
+| **Copyright:**       | Copyright (c) 2015 Chef Software Inc.
+
+| **Copyright:**       | Copyright (c) 2015 Vulcano Security GmbH.
+
+| **License:**         | Apache License, Version 2.0
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/Rakefile

@@ -0,0 +1,148 @@
+#!/usr/bin/env rake
+# encoding: utf-8
+
+require 'bundler'
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'rubocop/rake_task'
+
+# Rubocop
+desc 'Run Rubocop lint checks'
+task :rubocop do
+  RuboCop::RakeTask.new
+end
+
+# lint the project
+desc 'Run robocop linter'
+task lint: [:rubocop]
+
+# run tests
+task default: [:test, :lint]
+
+Rake::TestTask.new do |t|
+  t.libs << 'test/unit'
+  t.pattern = 'test/unit/**/*_test.rb'
+  t.warning = true
+  t.verbose = true
+  t.ruby_opts = ['--dev'] if defined?(JRUBY_VERSION)
+end
+
+namespace :test do
+  task :docker do
+    path = File.join(File.dirname(__FILE__), 'test', 'integration')
+    sh('sh', '-c', "cd #{path} && ruby -I ../../lib docker_test.rb tests/*")
+  end
+
+  task :windows do
+    Dir.glob('test/windows/*_test.rb').all? do |file|
+      sh(Gem.ruby, '-w', '-I .\test\windows', file)
+    end or fail 'Failures'
+  end
+
+  task :vm do
+    concurrency = ENV['CONCURRENCY'] || 4
+    path = File.join(File.dirname(__FILE__), 'test', 'integration')
+    sh('sh', '-c', "cd #{path} && kitchen test -c #{concurrency}")
+  end
+
+  # Target required:
+  #   rake "test:ssh[user@server]"
+  #   sh -c cd /home/foobarbam/src/gems/train/test/integration \
+  #     && target=user@server ruby -I ../../lib test_ssh.rb tests/*
+  #   ...
+  # Turn debug logging back on:
+  #   debug=1 rake "test:ssh[user@server]"
+  # Use a different ssh key:
+  #   key_files=/home/foobarbam/.ssh/id_rsa2 rake "test:ssh[user@server]"
+  # Run with a specific test:
+  #   test=path_block_device_test.rb rake "test:ssh[user@server]"
+  task :ssh, [:target] do |t, args|
+    path = File.join(File.dirname(__FILE__), 'test', 'integration')
+    key_files = ENV['key_files'] || File.join(ENV['HOME'], '.ssh', 'id_rsa')
+
+    sh_cmd    =  "cd #{path} && target=#{args[:target]} key_files=#{key_files}"
+
+    sh_cmd += " debug=#{ENV['debug']}" if ENV['debug']
+    sh_cmd += ' ruby -I ../../lib test_ssh.rb tests/'
+    sh_cmd += ENV['test'] || '*'
+
+    sh('sh', '-c', sh_cmd)
+  end
+end
+
+# Print the current version of this gem or update it.
+#
+# @param [Type] target the new version you want to set, or nil if you only want to show
+def train_version(target = nil)
+  path = 'lib/train/version.rb'
+  require_relative path.sub(/.rb$/, '')
+
+  nu_version = target.nil? ? '' : " -> #{target}"
+  puts "Train: #{Train::VERSION}#{nu_version}"
+
+  unless target.nil?
+    raw = File.read(path)
+    nu = raw.sub(/VERSION.*/, "VERSION = '#{target}'.freeze")
+    File.write(path, nu)
+    load(path)
+  end
+end
+
+# Check if a command is available
+#
+# @param [Type] x the command you are interested in
+# @param [Type] msg the message to display if the command is missing
+def require_command(x, msg = nil)
+  return if system("command -v #{x} || exit 1")
+  msg ||= 'Please install it first!'
+  puts "\033[31;1mCan't find command #{x.inspect}. #{msg}\033[0m"
+  exit 1
+end
+
+# Check if a required environment variable has been set
+#
+# @param [String] x the variable you are interested in
+# @param [String] msg the message you want to display if the variable is missing
+def require_env(x, msg = nil)
+  exists = `env | grep "^#{x}="`
+  return unless exists.empty?
+  puts "\033[31;1mCan't find environment variable #{x.inspect}. #{msg}\033[0m"
+  exit 1
+end
+
+# Check the requirements for running an update of this repository.
+def check_update_requirements
+  require_command 'git'
+  require_command 'github_changelog_generator', "\n"\
+    "For more information on how to install it see:\n"\
+    "  https://github.com/skywinder/github-changelog-generator\n"
+  require_env 'CHANGELOG_GITHUB_TOKEN', "\n"\
+    "Please configure this token to make sure you can run all commands\n"\
+    "against GitHub.\n\n"\
+    "See github_changelog_generator homepage for more information:\n"\
+    "  https://github.com/skywinder/github-changelog-generator\n"
+end
+
+# Show the current version of this gem.
+desc 'Show the version of this gem'
+task :version do
+  train_version
+end
+
+desc 'Generate the changelog'
+task :changelog do
+  require_relative 'lib/train/version'
+  system "github_changelog_generator -u chef -p train --future-release #{Train::VERSION}"
+end
+
+# Update the version of this gem and create an updated
+# changelog. It covers everything short of actually releasing
+# the gem.
+desc 'Bump the version of this gem'
+task :bump_version, [:version] do |_, args|
+  v = args[:version] || ENV['to']
+  fail "You must specify a target version!  rake bump_version to=1.2.3" if v.empty?
+  check_update_requirements
+  train_version(v)
+  Rake::Task['changelog'].invoke
+end

data/lib/train.rb

@@ -0,0 +1,117 @@
+# encoding: utf-8
+#
+# Author:: Dominik Richter (<dominik.richter@gmail.com>)
+
+require 'train/version'
+require 'train/plugins'
+require 'train/errors'
+require 'uri'
+
+module Train
+  # 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
+  def self.create(name, *args)
+    cls = load_transport(name)
+    cls.new(*args) unless cls.nil?
+  end
+
+  # Retrieve the configuration options of a transport plugin.
+  #
+  # @param [String] name of the plugin
+  # @return [Hash] map of default options
+  def self.options(name)
+    cls = load_transport(name)
+    cls.default_options unless cls.nil?
+  end
+
+  # 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
+  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
+
+  # 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
+  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
+
+  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
+
+  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
+end

data/lib/train/errors.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+#
+# Author:: Fletcher Nichol (<fnichol@nichol.ca>)
+# Author:: Dominik Richter (<dominik.richter@gmail.com>)
+# Author:: Christoph Hartmann (<chris@lollyrock.com>)
+#
+# Copyright (C) 2013, Fletcher Nichol
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+
+module Train
+  # Base exception class for all exceptions that are caused by user input
+  # errors.
+  class UserError < ::StandardError; end
+
+  # Base exception class for all exceptions that are caused by incorrect use
+  # of an API.
+  class ClientError < ::StandardError; end
+
+  # Base exception class for all exceptions that are caused by other failures
+  # in the transport layer.
+  class TransportError < ::StandardError; end
+end

data/lib/train/extras.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+#
+# Author:: Dominik Richter (<dominik.richter@gmail.com>)
+
+module Train::Extras
+  autoload :CommandWrapper, 'train/extras/command_wrapper'
+  autoload :FileCommon,     'train/extras/file_common'
+  autoload :AixFile,        'train/extras/file_aix'
+  autoload :UnixFile,       'train/extras/file_unix'
+  autoload :LinuxFile,      'train/extras/file_linux'
+  autoload :WindowsFile,    'train/extras/file_windows'
+  autoload :OSCommon,       'train/extras/os_common'
+  autoload :Stat,           'train/extras/stat'
+
+  CommandResult = Struct.new(:stdout, :stderr, :exit_status)
+  LoginCommand = Struct.new(:command, :arguments)
+end