winrm 1.8.1 → 2.0.0

data/lib/winrm.rb

@@ -1,42 +1,39 @@
-# encoding: UTF-8
-#
-# Copyright 2010 Dan Wanek <dan.wanek@gmail.com>
-#
-# 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 'date'
-require 'logging'
-require_relative 'winrm/version'
-
-# Main WinRM module entry point
-module WinRM
-  # Enable logging if it is requested. We do this before
-  # anything else so that we can setup the output before
-  # any logging occurs.
-  if ENV['WINRM_LOG'] && ENV['WINRM_LOG'] != ''
-    begin
-      Logging.logger.root.level = ENV['WINRM_LOG']
-      Logging.logger.root.appenders = Logging.appenders.stderr
-    rescue ArgumentError
-      # This means that the logging level wasn't valid
-      $stderr.puts "Invalid WINRM_LOG level is set: #{ENV['WINRM_LOG']}"
-      $stderr.puts ''
-      $stderr.puts 'Please use one of the standard log levels: ' \
-        'debug, info, warn, or error'
-    end
-  end
-end
-
-require 'winrm/output'
-require 'winrm/helpers/iso8601_duration'
-require 'winrm/soap_provider'
+# encoding: UTF-8
+#
+# Copyright 2010 Dan Wanek <dan.wanek@gmail.com>
+#
+# 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 'logging'
+require_relative 'winrm/version'
+require_relative 'winrm/connection'
+require_relative 'winrm/exceptions'
+
+# Main WinRM module entry point
+module WinRM
+  # Enable logging if it is requested. We do this before
+  # anything else so that we can setup the output before
+  # any logging occurs.
+  if ENV['WINRM_LOG'] && ENV['WINRM_LOG'] != ''
+    begin
+      Logging.logger.root.level = ENV['WINRM_LOG']
+      Logging.logger.root.appenders = Logging.appenders.stderr
+    rescue ArgumentError
+      # This means that the logging level wasn't valid
+      $stderr.puts "Invalid WINRM_LOG level is set: #{ENV['WINRM_LOG']}"
+      $stderr.puts ''
+      $stderr.puts 'Please use one of the standard log levels: ' \
+        'debug, info, warn, or error'
+    end
+  end
+end

data/lib/winrm/connection.rb

@@ -0,0 +1,82 @@
+# -*- encoding: utf-8 -*-
+#
+# Copyright 2016 Shawn Neal <sneal@sneal.net>
+#
+# 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_relative 'connection_opts'
+require_relative 'http/transport_factory'
+require_relative 'shells/shell_factory'
+require_relative 'wsmv/wql_query'
+
+module WinRM
+  # WinRM connection used to establish a session with the remote WinRM service.
+  class Connection
+    # Creates a new WinRM connection
+    # See the ConnectionOpts class for connection options.
+    def initialize(connection_opts)
+      configure_connection_opts(connection_opts)
+      configure_logger
+    end
+
+    attr_accessor :logger
+
+    # Creates a new shell on the remote Windows server associated with
+    # this connection.
+    # @param shell_type [Symbol] The shell type :cmd or :powershell
+    # @return [Shell] PowerShell or Cmd shell instance.
+    def shell(shell_type)
+      shell = shell_factory.create_shell(shell_type)
+      if block_given?
+        begin
+          yield shell
+        ensure
+          shell.close
+        end
+      else
+        shell
+      end
+    end
+
+    # Executes a WQL query against the WinRM connection
+    # @param wql [String] The wql query
+    # @return [Hash] Hash representation of wql query response
+    def run_wql(wql)
+      query = WinRM::WSMV::WqlQuery.new(@connection_opts, wql)
+      query.process_response(transport.send_request(query.build))
+    end
+
+    private
+
+    def configure_connection_opts(connection_opts)
+      @connection_opts = ConnectionOpts.create_with_defaults(connection_opts)
+    end
+
+    def configure_logger
+      @logger = Logging.logger[self]
+      logger.level = :warn
+      logger.add_appenders(Logging.appenders.stdout)
+    end
+
+    def shell_factory
+      @shell_factory ||= WinRM::Shells::ShellFactory.new(@connection_opts, transport, logger)
+    end
+
+    def transport
+      @transport ||= begin
+        transport_factory = WinRM::HTTP::TransportFactory.new
+        transport_factory.create_transport(@connection_opts)
+      end
+    end
+  end
+end

data/lib/winrm/connection_opts.rb

@@ -0,0 +1,87 @@
+# -*- encoding: utf-8 -*-
+#
+# Copyright 2016 Shawn Neal <sneal@sneal.net>
+#
+# 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 'securerandom'
+
+module WinRM
+  # WinRM connection options, provides defaults and validation.
+  class ConnectionOpts < Hash
+    DEFAULT_OPERATION_TIMEOUT = 60
+    DEFAULT_RECEIVE_TIMEOUT = DEFAULT_OPERATION_TIMEOUT + 10
+    DEFAULT_MAX_ENV_SIZE = 153600
+    DEFAULT_LOCALE = 'en-US'.freeze
+    DEFAULT_RETRY_DELAY = 10
+    DEFAULT_RETRY_LIMIT = 3
+
+    class << self
+      def create_with_defaults(overrides)
+        config = default.merge(overrides)
+        config = ensure_receive_timeout_is_greater_than_operation_timeout(config)
+        config.validate
+        config
+      end
+
+      private
+
+      def ensure_receive_timeout_is_greater_than_operation_timeout(config)
+        if config[:receive_timeout] < config[:operation_timeout]
+          config[:receive_timeout] = config[:operation_timeout] + 10
+        end
+        config
+      end
+
+      def default
+        config = ConnectionOpts.new
+        config[:session_id] = SecureRandom.uuid.to_s.upcase
+        config[:transport] = :negotiate
+        config[:locale] = DEFAULT_LOCALE
+        config[:max_envelope_size] = DEFAULT_MAX_ENV_SIZE
+        config[:operation_timeout] = DEFAULT_OPERATION_TIMEOUT
+        config[:receive_timeout] = DEFAULT_RECEIVE_TIMEOUT
+        config[:retry_delay] = DEFAULT_RETRY_DELAY
+        config[:retry_limit] = DEFAULT_RETRY_LIMIT
+        config
+      end
+    end
+
+    def validate
+      validate_required_fields
+      validate_data_types
+    end
+
+    private
+
+    def validate_required_fields
+      raise 'endpoint is a required option' unless self[:endpoint]
+      raise 'user is a required option' unless self[:user]
+      raise 'password is a required option' unless self[:password]
+    end
+
+    def validate_data_types
+      validate_fixnum(:retry_limit)
+      validate_fixnum(:retry_delay)
+      validate_fixnum(:max_envelope_size)
+      validate_fixnum(:operation_timeout)
+      validate_fixnum(:receive_timeout, self[:operation_timeout])
+    end
+
+    def validate_fixnum(key, min = 0)
+      value = self[key]
+      raise "#{key} must be a Fixnum" unless value && value.is_a?(Fixnum)
+      raise "#{key} must be greater than #{min}" unless value > min
+    end
+  end
+end

data/lib/winrm/{exceptions/exceptions.rb → exceptions.rb}

@@ -1,57 +1,76 @@
-# encoding: UTF-8
-#
-# Copyright 2010 Dan Wanek <dan.wanek@gmail.com>
-#
-# 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.
-
-module WinRM
-  # WinRM base class for errors
-  class WinRMError < StandardError; end
-
-  # Authorization Error
-  class WinRMAuthorizationError < WinRMError; end
-
-  # A Fault returned in the SOAP response. The XML node is a WSManFault
-  class WinRMWSManFault < WinRMError
-    attr_reader :fault_code
-    attr_reader :fault_description
-
-    def initialize(fault_description, fault_code)
-      @fault_description = fault_description
-      @fault_code = fault_code
-      super("[WSMAN ERROR CODE: #{fault_code}]: #{fault_description}")
-    end
-  end
-
-  # A Fault returned in the SOAP response. The XML node is a MSFT_WmiError
-  class WinRMWMIError < WinRMError
-    attr_reader :error_code
-    attr_reader :error
-
-    def initialize(error, error_code)
-      @error = error
-      @error_code = error_code
-      super("[WMI ERROR CODE: #{error_code}]: #{error}")
-    end
-  end
-
-  # non-200 response without a SOAP fault
-  class WinRMHTTPTransportError < WinRMError
-    attr_reader :status_code
-
-    def initialize(msg, status_code)
-      @status_code = status_code
-      super(msg + " (#{status_code}).")
-    end
-  end
-end
+# encoding: UTF-8
+#
+# Copyright 2010 Dan Wanek <dan.wanek@gmail.com>
+#
+# 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.
+
+module WinRM
+  # WinRM base class for errors
+  class WinRMError < StandardError; end
+
+  # Authorization Error
+  class WinRMAuthorizationError < WinRMError; end
+
+  # Shell creation error
+  class InvalidShellError < WinRMError; end
+
+  # Exitcode error
+  class InvalidExitCode < WinRMError; end
+
+  # Shell creation error
+  class InvalidTransportError < WinRMError
+    attr_reader :invalid_transport
+
+    def initialize(invalid_transport, valid_transports)
+      @invalid_transport = invalid_transport
+      super(
+        "Invalid transport '#{invalid_transport}' specified" \
+        ", expected: #{valid_transports.join(', ')}."
+      )
+    end
+  end
+
+  # A Fault returned in the SOAP response. The XML node is a WSManFault
+  class WinRMWSManFault < WinRMError
+    attr_reader :fault_code
+    attr_reader :fault_description
+
+    def initialize(fault_description, fault_code)
+      @fault_description = fault_description
+      @fault_code = fault_code
+      super("[WSMAN ERROR CODE: #{fault_code}]: #{fault_description}")
+    end
+  end
+
+  # A Fault returned in the SOAP response. The XML node is a MSFT_WmiError
+  class WinRMWMIError < WinRMError
+    attr_reader :error_code
+    attr_reader :error
+
+    def initialize(error, error_code)
+      @error = error
+      @error_code = error_code
+      super("[WMI ERROR CODE: #{error_code}]: #{error}")
+    end
+  end
+
+  # non-200 response without a SOAP fault
+  class WinRMHTTPTransportError < WinRMError
+    attr_reader :status_code
+
+    def initialize(msg, status_code = nil)
+      @status_code = status_code
+      super(msg + " (#{status_code}).")
+    end
+  end
+end

data/lib/winrm/http/response_handler.rb

@@ -1,82 +1,96 @@
-# encoding: UTF-8
-#
-# Copyright 2014 Shawn Neal <sneal@sneal.net>
-#
-# 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 'rexml/document'
-
-module WinRM
-  # Handles the raw WinRM HTTP response. Returns the body as an XML doc
-  # or raises the appropriate WinRM error if the response is an error.
-  class ResponseHandler
-    # @param [String] The raw unparsed response body, if any
-    # @param [Integer] The HTTP response status code
-    def initialize(response_body, status_code)
-      @response_body = response_body
-      @status_code = status_code
-    end
-
-    # Processes the response from the WinRM service and either returns an XML
-    # doc or raises an appropriate error.
-    #
-    # @returns [REXML::Document] The parsed response body
-    def parse_to_xml
-      raise_if_error
-      response_xml
-    end
-
-    private
-
-    def response_xml
-      @response_xml ||= REXML::Document.new(@response_body)
-    rescue REXML::ParseException => e
-      raise WinRMHTTPTransportError.new(
-        "Unable to parse WinRM response: #{e.message}", @status_code)
-    end
-
-    def raise_if_error
-      return if @status_code == 200
-      raise_if_auth_error
-      raise_if_wsman_fault
-      raise_if_wmi_error
-      raise_transport_error
-    end
-
-    def raise_if_auth_error
-      fail WinRMAuthorizationError if @status_code == 401
-    end
-
-    def raise_if_wsman_fault
-      soap_errors = REXML::XPath.match(response_xml, "//#{NS_SOAP_ENV}:Body/#{NS_SOAP_ENV}:Fault/*")
-      return if soap_errors.empty?
-      fault = REXML::XPath.first(soap_errors, "//#{NS_WSMAN_FAULT}:WSManFault")
-      fail WinRMWSManFault.new(fault.to_s, fault.attributes['Code']) unless fault.nil?
-    end
-
-    def raise_if_wmi_error
-      soap_errors = REXML::XPath.match(response_xml, "//#{NS_SOAP_ENV}:Body/#{NS_SOAP_ENV}:Fault/*")
-      return if soap_errors.empty?
-
-      error = REXML::XPath.first(soap_errors, "//#{NS_WSMAN_MSFT}:MSFT_WmiError")
-      return if error.nil?
-
-      error_code = REXML::XPath.first(error, "//#{NS_WSMAN_MSFT}:error_Code").text
-      fail WinRMWMIError.new(error.to_s, error_code)
-    end
-
-    def raise_transport_error
-      fail WinRMHTTPTransportError.new('Bad HTTP response returned from server', @status_code)
-    end
-  end
-end
+# encoding: UTF-8
+#
+# Copyright 2014 Shawn Neal <sneal@sneal.net>
+#
+# 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 'rexml/document'
+require_relative '../wsmv/soap'
+
+module WinRM
+  # Handles the raw WinRM HTTP response. Returns the body as an XML doc
+  # or raises the appropriate WinRM error if the response is an error.
+  class ResponseHandler
+    # @param [String] The raw unparsed response body, if any
+    # @param [Integer] The HTTP response status code
+    def initialize(response_body, status_code)
+      @response_body = response_body
+      @status_code = status_code
+    end
+
+    # Processes the response from the WinRM service and either returns an XML
+    # doc or raises an appropriate error.
+    #
+    # @returns [REXML::Document] The parsed response body
+    def parse_to_xml
+      raise_if_error
+      response_xml
+    end
+
+    private
+
+    def response_xml
+      @response_xml ||= REXML::Document.new(@response_body)
+    rescue REXML::ParseException => e
+      raise WinRMHTTPTransportError.new(
+        "Unable to parse WinRM response: #{e.message}", @status_code)
+    end
+
+    def raise_if_error
+      return if @status_code == 200
+      raise_if_auth_error
+      raise_if_wsman_fault
+      raise_if_wmi_error
+      raise_transport_error
+    end
+
+    def raise_if_auth_error
+      raise WinRMAuthorizationError if @status_code == 401
+    end
+
+    def raise_if_wsman_fault
+      soap_errors = REXML::XPath.match(
+        response_xml,
+        "//#{WinRM::WSMV::SOAP::NS_SOAP_ENV}:Body/#{WinRM::WSMV::SOAP::NS_SOAP_ENV}:Fault/*")
+      return if soap_errors.empty?
+      fault = REXML::XPath.first(
+        soap_errors,
+        "//#{WinRM::WSMV::SOAP::NS_WSMAN_FAULT}:WSManFault")
+      raise WinRMWSManFault.new(fault.to_s, fault.attributes['Code']) unless fault.nil?
+    end
+
+    def raise_if_wmi_error
+      soap_errors = REXML::XPath.match(
+        response_xml,
+        "//#{WinRM::WSMV::SOAP::NS_SOAP_ENV}:Body/#{WinRM::WSMV::SOAP::NS_SOAP_ENV}:Fault/*")
+      return if soap_errors.empty?
+
+      error = REXML::XPath.first(
+        soap_errors,
+        "//#{WinRM::WSMV::SOAP::NS_WSMAN_MSFT}:MSFT_WmiError")
+      return if error.nil?
+
+      error_code = REXML::XPath.first(
+        error,
+        "//#{WinRM::WSMV::SOAP::NS_WSMAN_MSFT}:error_Code").text
+      raise WinRMWMIError.new(error.to_s, error_code)
+    end
+
+    def raise_transport_error
+      raise WinRMHTTPTransportError.new(
+        "Bad HTTP response returned from server. Body(if present):#{@response_body}",
+        @status_code
+      )
+    end
+  end
+end