winrm-transport 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8fceb01bb304b3dbde260f959336ea7dc319dd81
+  data.tar.gz: 35dfc04b0d86e4ec094e6646b2e0ffc34224e623
+SHA512:
+  metadata.gz: 5ea5f23b2e9bc90cd2fe5c8db87b18fed3b5061e9b4858160cef498583b07c0ca7fc47da1a22f33e244b17a17bef653233070456fc953afa1f27bcfac1b2a0d0
+  data.tar.gz: d2ac24211bd20bc50cfaae3c5c02c430293bf5701975072fb50cb429948db816551aa9a486ee136b69193c475f17665e9455ee30eaf566c22e078a012ff4be4b

data/.cane

@@ -0,0 +1,2 @@
+--abc-max 20
+--style-measure 100

data/.gitignore

@@ -0,0 +1,15 @@
+*.gem
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/.rvmrc
+/.rbenv-version
+/.ruby-version
+/.project
+/.DS_Store

data/.travis.yml

@@ -0,0 +1,26 @@
+language: ruby
+
+rvm:
+  - 2.2
+  - 2.1
+  - 2.0.0
+  - 1.9.3
+  - ruby-head
+
+before_install:
+  - echo "Updating Bundler to ~> 1.9 until TravisCI has upgraded."
+  - gem install bundler -v "~> 1.9"
+  - bundle --version
+
+bundler_args: --without guard
+
+sudo: false
+
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+
+addons:
+  code_climate:
+    repo_token:
+      secure: "WSrIaJVtAh88T7cd3DQY38yxiDz44Oms4Z5Dm+mVUv8gpKWixMR3t5ShmDW8+XXWWj3s3WUa2t5yZugrfz0gkrKCxSII6VURakBKy2jEKnEnJWoh8LKYjXHYW2fOU/PpclSFl0Ynxvt8Nn/F9dpbaGAqj2DwycAV4EtByuy06X0="

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 1.0.0 / 2015-03-29
+
+The initial release.

data/Gemfile

@@ -0,0 +1,13 @@
+# -*- encoding: utf-8 -*-
+source "https://rubygems.org"
+gemspec
+
+group :guard do
+  gem "guard-minitest"
+  gem "guard-rubocop"
+  gem "guard-yard"
+end
+
+group :test do
+  gem "codeclimate-test-reporter", :require => nil
+end

data/Guardfile

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+ignore %r{^\.gem/}
+
+def rubocop_opts
+  { :all_on_start => false, :keep_failed => false, :cli => "-r finstyle" }
+end
+
+def yard_opts
+  { :port => "8808" }
+end
+
+group :red_green_refactor, :halt_on_fail => true do
+  guard :minitest do
+    watch(%r{^spec/(.*)_spec\.rb})
+    watch(%r{^lib/(.*)([^/]+)\.rb})     { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+    watch(%r{^spec/spec_helper\.rb})    { "spec" }
+  end
+
+  guard :rubocop, rubocop_opts do
+    watch(%r{.+\.rb$})
+    watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
+  end
+end
+
+guard :yard, yard_opts do
+  watch(%r{lib/.+\.rb})
+end

data/LICENSE.txt

@@ -0,0 +1,15 @@
+Author:: Fletcher Nichol (<fnichol@nichol.ca>)
+
+Copyright 2015 Fletcher Nichol
+
+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/README.md

@@ -0,0 +1,80 @@
+# WinRM::Transport
+
+[![Gem Version](https://badge.fury.io/rb/winrm-transport.svg)](http://badge.fury.io/rb/winrm-transport)
+[![Build Status](https://secure.travis-ci.org/test-kitchen/winrm-transport.svg?branch=master)](https://travis-ci.org/test-kitchen/winrm-transport)
+[![Code Climate](https://codeclimate.com/github/test-kitchen/winrm-transport.svg)](https://codeclimate.com/github/test-kitchen/winrm-transport)
+[![Test Coverage](https://codeclimate.com/github/test-kitchen/winrm-transport/badges/coverage.svg)](https://codeclimate.com/github/test-kitchen/winrm-transport)
+[![Inline docs](http://inch-ci.org/github/test-kitchen/winrm-transport.svg?branch=master)](http://inch-ci.org/github/test-kitchen/winrm-transport)
+[![Dependency Status](https://gemnasium.com/test-kitchen/winrm-transport.svg)](https://gemnasium.com/test-kitchen/winrm-transport)
+
+WinRM transport logic for re-using remote shells and uploading files. The original code was extracted from the [Test Kitchen][test_kitchen] project and remains the primary reference use case.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'winrm-transport'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install winrm-transport
+
+## Usage
+
+This a library gem and doesn't have any CLI commands. There are 2 primary object classes:
+
+* [WinRM::Transport::CommandExecutor][command_executor]: an object which can
+  execute multiple commands and PowerShell script in one shared remote shell
+  session.
+* [WinRM::Transport::FileTransporter][file_transporter]: an object which can
+  upload one or more files or directories to a remote host over WinRM only
+  using PowerShell scripts and CMD commands.
+
+## Versioning
+
+WinRM::Transport aims to adhere to [Semantic Versioning 2.0.0][semver].
+
+## Development
+
+* Source hosted at [GitHub][repo]
+* Report issues/questions/feature requests on [GitHub Issues][issues]
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bin/console` for an interactive prompt that will allow you to experiment.
+
+## Contributing
+
+Pull requests are very welcome! Make sure your patches are well tested.
+Ideally create a topic branch for every separate change you make. For
+example:
+
+1. Fork it ( https://github.com/test-kitchen/winrm-transport/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## Authors
+
+Created and maintained by [Fletcher Nichol][fnichol] (<fnichol@nichol.ca>) and
+a growing community of [contributors][contributors].
+
+## License
+
+Apache License, Version 2.0 (see [LICENSE.txt][license])
+
+[command_executor]: https://github.com/test-kitchen/winrm-transport/blob/master/lib/winrm/transport/command_executor.rb
+[contributors]: https://github.com/test-kitchen/winrm-transport/graphs/contributors
+[file_transporter]: https://github.com/test-kitchen/winrm-transport/blob/master/lib/winrm/transport/file_transporter.rb
+[fnichol]: https://github.com/fnichol
+[issues]: https://github.com/test-kitchen/winrm-transpor/issues
+[license]: https://github.com/test-kitchen/winrm-transport/blob/master/LICENSE.txt
+[repo]: https://github.com/test-kitchen/winrm-transport
+[semver]: http://semver.org/
+[test_kitchen]: http://kitchen.ci

data/Rakefile

@@ -0,0 +1,49 @@
+# -*- encoding: utf-8 -*-
+
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+Rake::TestTask.new(:unit) do |t|
+  t.libs.push "lib"
+  t.test_files = FileList["spec/**/*_spec.rb"]
+  t.verbose = true
+end
+
+desc "Run all test suites"
+task :test => [:unit]
+
+desc "Display LOC stats"
+task :stats do
+  puts "\n## Production Code Stats"
+  sh "countloc -r lib"
+  puts "\n## Test Code Stats"
+  sh "countloc -r spec"
+end
+
+require "finstyle"
+require "rubocop/rake_task"
+RuboCop::RakeTask.new(:style) do |task|
+  task.options << "--display-cop-names"
+end
+
+require "cane/rake_task"
+desc "Run cane to check quality metrics"
+Cane::RakeTask.new do |cane|
+  cane.canefile = "./.cane"
+end
+
+desc "Run all quality tasks"
+task :quality => [:cane, :style, :stats]
+
+require "yard"
+YARD::Rake::YardocTask.new
+
+desc "Generate gem dependency graph"
+task :viz do
+  Bundler.with_clean_env do
+    sh "bundle viz --without test development guard " \
+      "--requirements --version"
+  end
+end
+
+task :default => [:test, :quality]

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "winrm/transport"
+
+require "pry"
+Pry.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/winrm/transport.rb

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+#
+# Author:: Fletcher Nichol (<fnichol@nichol.ca>)
+#
+# Copyright (C) 2015, Fletcher Nichol
+#
+# 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.
+
+require "winrm/transport/version"
+
+module WinRM
+
+  # WinRM transport logic for re-using remote shells and uploading files.
+  #
+  # @author Fletcher Nichol <fnichol@nichol.ca>
+  module Transport
+  end
+end

data/lib/winrm/transport/command_executor.rb

@@ -0,0 +1,217 @@
+# -*- encoding: utf-8 -*-
+#
+# Author:: Matt Wrock (<matt@mattwrock.com>)
+#
+# Copyright (C) 2014, Matt Wrock
+#
+# 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.
+
+require "winrm/transport/logging"
+
+module WinRM
+
+  module Transport
+
+    # Object which can execute multiple commands and Powershell scripts in
+    # one shared remote shell session. The maximum number of commands per
+    # shell is determined by interrogating the remote host when the session
+    # is opened and the remote shell is automatically recycled before the
+    # threshold is reached.
+    #
+    # @author Matt Wrock <matt@mattwrock.com>
+    # @author Fletcher Nichol <fnichol@nichol.ca>
+    class CommandExecutor
+
+      include Logging
+
+      # @return [Integer,nil] the safe maximum number of commands that can
+      #   be executed in one remote shell session, or `nil` if the
+      #   threshold has not yet been determined
+      attr_reader :max_commands
+
+      # @return [String,nil] the identifier for the current open remote
+      #   shell session, or `nil` if the session is not open
+      attr_reader :shell
+
+      # Creates a CommandExecutor given a `WinRM::WinRMWebService` object.
+      #
+      # @param service [WinRM::WinRMWebService] a winrm web service object
+      # @param logger [#debug,#info] an optional logger/ui object that
+      #   responds to `#debug` and `#info` (default: `nil`)
+      # @param closer [ShellCloser] an optional object to automatically
+      #   close the active open remote shell when CommandExecutor garbarge
+      #   collects
+      def initialize(service, logger = nil, closer = nil)
+        @service        = service
+        @logger         = logger
+        @closer         = closer
+        @command_count  = 0
+      end
+
+      # Closes the open remote shell session. This method can be called
+      # multiple times, even if there is no open session.
+      def close
+        return if shell.nil?
+
+        service.close_shell(shell)
+        remove_finalizer
+        @shell = nil
+      end
+
+      # Opens a remote shell session for reuse. The maxiumum
+      # command-per-shell threshold is also determined the first time this
+      # method is invoked and cached for later invocations.
+      #
+      # @return [String] the remote shell session indentifier
+      def open
+        close
+        @shell = service.open_shell
+        add_finalizer(shell)
+        @command_count = 0
+        determine_max_commands unless max_commands
+        shell
+      end
+
+      # Runs a CMD command.
+      #
+      # @param command [String] the command to run on the remote system
+      # @param arguments [Array<String>] arguments to the command
+      # @yield [stdout, stderr] yields more live access the standard
+      #   output and standard error streams as they are returns, if
+      #   streaming behavior is desired
+      # @return [WinRM::Output] output object with stdout, stderr, and
+      #   exit code
+      def run_cmd(command, arguments = [], &block)
+        reset if command_count_exceeded?
+        ensure_open_shell!
+
+        @command_count += 1
+        result = nil
+        service.run_command(shell, command, arguments) do |command_id|
+          result = service.get_command_output(shell, command_id, &block)
+        end
+        result
+      end
+
+      # Run a Powershell script that resides on the local box.
+      #
+      # @param script_file [IO,String] an IO reference for reading the
+      #   Powershell script or the actual file contents
+      # @yield [stdout, stderr] yields more live access the standard
+      #   output and standard error streams as they are returns, if
+      #   streaming behavior is desired
+      # @return [WinRM::Output] output object with stdout, stderr, and
+      #   exit code
+      def run_powershell_script(script_file, &block)
+        # this code looks overly compact in an attempt to limit local
+        # variable assignments that may contain large strings and
+        # consequently bloat the Ruby VM
+        run_cmd(
+          "powershell",
+          [
+            "-encodedCommand",
+            ::WinRM::PowershellScript.new(
+              script_file.is_a?(IO) ? script_file.read : script_file
+            ).encoded
+          ],
+          &block
+        )
+      end
+
+      private
+
+      # @return [Integer] the default maximum number of commands which can be
+      #   executed in one remote shell session on "older" versions of Windows
+      # @api private
+      LEGACY_LIMIT = 15
+
+      # @return [Integer] the default maximum number of commands which can be
+      #   executed in one remote shell session on "modern" versions of Windows
+      # @api private
+      MODERN_LIMIT = 1500
+
+      # @return [String] the PowerShell command used to determine the version
+      #   of Windows
+      # @api private
+      PS1_OS_VERSION = "[environment]::OSVersion.Version.tostring()".freeze
+
+      # @return [Integer] the number of executed commands on the remote
+      #   shell session
+      # @api private
+      attr_accessor :command_count
+
+      # @return [#debug,#info] the logger
+      # @api private
+      attr_reader :logger
+
+      # @return [WinRM::WinRMWebService] a WinRM web service object
+      # @api private
+      attr_reader :service
+
+      # Creates a finalizer for this connection which will close the open
+      # remote shell session when the object is garabage collected or on
+      # Ruby VM shutdown.
+      #
+      # @param shell_id [String] the remote shell identifier
+      # @api private
+      def add_finalizer(shell_id)
+        ObjectSpace.define_finalizer(self, @closer.for(shell_id)) if @closer
+      end
+
+      # @return [true,false] whether or not the number of exeecuted commands
+      #   have exceeded the maxiumum threshold
+      # @api private
+      def command_count_exceeded?
+        command_count > max_commands.to_i
+      end
+
+      # Ensures that there is an open remote shell session.
+      #
+      # @raise [WinRM::WinRMError] if there is no open shell
+      # @api private
+      def ensure_open_shell!
+        if shell.nil?
+          raise ::WinRM::WinRMError, "#{self.class}#open must be called " \
+            "before any run methods are invoked"
+        end
+      end
+
+      # Determines the safe maximum number of commands that can be executed
+      # on a remote shell session by interrogating the remote host.
+      #
+      # @api private
+      def determine_max_commands
+        os_version = run_powershell_script(PS1_OS_VERSION).stdout.chomp
+        @max_commands = os_version < "6.2" ? LEGACY_LIMIT : MODERN_LIMIT
+        @max_commands -= 2 # to be safe
+      end
+
+      # Removes any finalizers for this connection.
+      #
+      # @api private
+      def remove_finalizer
+        ObjectSpace.undefine_finalizer(self) if @closer
+      end
+
+      # Closes the remote shell session and opens a new one.
+      #
+      # @api private
+      def reset
+        debug {
+          "Resetting WinRM shell (Max command limit is #{max_commands})"
+        }
+        open
+      end
+    end
+  end
+end