kitchen-hyperv 0.10.3 → 0.12.0

data/lib/kitchen/driver/powershell.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 #
 # Author:: Steven Murawski <smurawski@chef.io>
 # Copyright:: Copyright (c) 2020 Chef Software, Inc.
@@ -15,41 +17,135 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "mixlib/shellout" unless defined?(Mixlib::ShellOut)
+require "base64" unless defined?(Base64)
 require "benchmark" unless defined?(Benchmark)
+require "rbconfig/sizeof" unless defined?(RbConfig::SIZEOF)
 require "fileutils" unless defined?(FileUtils)
 require "json" unless defined?(JSON)
 
 module Kitchen
   module Driver
+    # PowerShell generation and execution for {Kitchen::Driver::Hyperv}.
+    #
+    # Every method here is either a script generator -- a `*_ps` method
+    # returning PowerShell source -- or part of the pipeline that runs one:
+    # {#run_ps} wraps the script so it dot-sources `support/hyperv.ps1`,
+    # {#encode_command} encodes it for `powershell.exe -encodedcommand`, and
+    # {#execute_command} runs it over the Train connection and parses the JSON
+    # that comes back.
+    #
+    # Encoding sidesteps every layer of quoting between Ruby and PowerShell,
+    # which matters because these scripts embed Windows paths and user-supplied
+    # strings.
+    #
+    # The module reads `config`, `instance` and `@state` from the driver it is
+    # mixed into, so it is not usable standalone.
+    #
+    # @see Kitchen::Driver::Hyperv
     module PowerShellScripts
+      # Values Windows reports in PROCESSOR_ARCHITECTURE for a 64-bit OS.
+      #
+      # ARM64 matters for Windows on ARM devices, which run Hyper-V: matching
+      # only AMD64 there made both width checks false and sent the driver to
+      # the Sysnative path, which does not exist for a native 64-bit process.
+      SIXTY_FOUR_BIT_ARCHITECTURES = %w{AMD64 ARM64 IA64}.freeze
+
+      # Encode a script the way `powershell.exe -encodedcommand` expects it:
+      # UTF-16LE, then Base64.
+      #
+      # @param script [String] UTF-8 PowerShell source
+      # @return [String] strict Base64, with no line breaks
+      # @api private
       def encode_command(script)
         encoded_script = script.encode("UTF-16LE", "UTF-8")
         Base64.strict_encode64(encoded_script)
       end
 
-      def is_64bit?
+      # The OS architecture, seeing through WOW64.
+      #
+      # A 32-bit process on 64-bit Windows reads its own architecture from
+      # PROCESSOR_ARCHITECTURE; PROCESSOR_ARCHITEW6432 is what reveals the real
+      # one, and is only set in that case.
+      #
+      # @return [String, nil]
+      # @api private
+      def os_architecture
+        ENV["PROCESSOR_ARCHITEW6432"] || ENV["PROCESSOR_ARCHITECTURE"]
+      end
+
+      # Pointer width of the running Ruby, in bits.
+      #
+      # @return [Integer] 32 or 64
+      # @api private
+      def ruby_architecture_bits
+        RbConfig::SIZEOF.fetch("void*", 8) * 8
+      end
+
+      # Whether a 64-bit PowerShell is directly reachable.
+      #
+      # Always true for a remote host, where the local architecture is
+      # irrelevant.
+      #
+      # @return [Boolean]
+      # @api private
+      def sixty_four_bit?
         return true if remote_hyperv
 
-        os_arch = ENV["PROCESSOR_ARCHITEW6432"] || ENV["PROCESSOR_ARCHITECTURE"]
-        ruby_arch = ["foo"].pack("p").size == 4 ? 32 : 64
-        os_arch == "AMD64" && ruby_arch == 64
+        SIXTY_FOUR_BIT_ARCHITECTURES.include?(os_architecture) &&
+          ruby_architecture_bits == 64
+      end
+
+      # Whether both the OS and Ruby are 32-bit, so no WOW64 redirection is in
+      # play.
+      #
+      # @return [Boolean]
+      # @api private
+      def thirty_two_bit?
+        !SIXTY_FOUR_BIT_ARCHITECTURES.include?(os_architecture) &&
+          ruby_architecture_bits == 32
+      end
+
+      # @deprecated Use {#sixty_four_bit?}. Kept because this module is mixed
+      #   into a published driver class.
+      # @return [Boolean]
+      # @api private
+      def is_64bit?
+        sixty_four_bit?
       end
 
+      # @deprecated Use {#thirty_two_bit?}. Kept because this module is mixed
+      #   into a published driver class.
+      # @return [Boolean]
+      # @api private
       def is_32bit?
-        os_arch = ENV["PROCESSOR_ARCHITEW6432"] || ENV["PROCESSOR_ARCHITECTURE"]
-        ruby_arch = ["foo"].pack("p").size == 4 ? 32 : 64
-        os_arch != "AMD64" && ruby_arch == 32
+        thirty_two_bit?
       end
 
+      # Path to a PowerShell that can see the Hyper-V cmdlets.
+      #
+      # When a 32-bit Ruby runs on 64-bit Windows the WOW64 filesystem
+      # redirector rewrites `system32` to `SysWOW64`, which would launch a
+      # 32-bit PowerShell with no Hyper-V module. `sysnative` is the virtual
+      # path that escapes redirection.
+      #
+      # @return [String]
+      # @api private
       def powershell_64_bit
-        if is_64bit? || is_32bit?
+        if sixty_four_bit? || thirty_two_bit?
           'c:\windows\system32\windowspowershell\v1.0\powershell.exe'
         else
           'c:\windows\sysnative\windowspowershell\v1.0\powershell.exe'
         end
       end
 
+      # Turn a script into a full `powershell.exe` command line.
+      #
+      # Prepends a dot-source of the support script so the helper functions are
+      # defined, then encodes the result.
+      #
+      # @param script [String] PowerShell source
+      # @return [String] the command line to hand to the connection
+      # @api private
       def wrap_command(script)
         debug("Loading functions from #{base_script_path}")
         new_script = [ ". #{base_script_path}", "#{script}" ].join(";\n")
@@ -58,11 +154,16 @@ module Kitchen
         " -encodedcommand #{encode_command new_script} -outputformat Text"
       end
 
-      # Convenience method to run a powershell command locally.
+      # Run a PowerShell script on the Hyper-V host.
       #
-      # @param cmd [String] command to run locally
-      # @param options [Hash] options hash
-      # @see Kitchen::ShellOut.run_command
+      # With `dry_run` set the script is echoed rather than executed, which is
+      # the quickest way to see exactly what the driver would have run.
+      #
+      # @param cmd [String] PowerShell source
+      # @param options [Hash] options passed through to the Train connection
+      # @return [Hash, Array, nil] the parsed JSON output, or nil when the
+      #   script produced none
+      # @raise [RuntimeError] if the script exits non-zero
       # @api private
       def run_ps(cmd, options = {})
         cmd = "echo #{cmd}" if config[:dry_run]
@@ -72,6 +173,14 @@ module Kitchen
         execute_command wrapped_command, options
       end
 
+      # Run a prepared command line and parse its output.
+      #
+      # @param cmd [String] the full command line from {#wrap_command}
+      # @param options [Hash] options passed through to the Train connection
+      # @return [Hash, Array, nil] the parsed JSON output, or nil when the
+      #   script produced none
+      # @raise [RuntimeError] if the command exits non-zero
+      # @api private
       def execute_command(cmd, options = {})
         debug("#Command BEGIN (#{cmd})")
 
@@ -87,10 +196,21 @@ module Kitchen
         JSON.parse(stdout) if stdout.length > 2
       end
 
+      # Strip the interactive prompt lines PowerShell interleaves with output,
+      # which would otherwise make the result invalid JSON.
+      #
+      # @param stdout [String] raw stdout from the host
+      # @return [String] stdout with prompt lines removed
+      # @api private
       def sanitize_stdout(stdout)
         stdout.split("\n").select { |s| !s.start_with?("PS") }.join("\n")
       end
 
+      # Script that clones the parent VHD into this instance's differencing
+      # disk.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def new_differencing_disk_ps
         <<-DIFF
 
@@ -98,6 +218,12 @@ module Kitchen
         DIFF
       end
 
+      # Script that creates one additional data disk.
+      #
+      # @param disk_path [String] full path of the disk to create
+      # @param disk_size [Integer] size in gigabytes
+      # @return [String] PowerShell source
+      # @api private
       def new_additional_disk_ps(disk_path, disk_size)
         <<-ADDDISK
 
@@ -105,6 +231,10 @@ module Kitchen
         ADDDISK
       end
 
+      # Script that confirms the VM exists and starts it if it is stopped.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def ensure_vm_running_ps
         <<-RUNNING
 
@@ -112,6 +242,10 @@ module Kitchen
         RUNNING
       end
 
+      # Script that creates the VM from the current configuration.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def new_vm_ps
         <<-NEWVM
 
@@ -137,6 +271,14 @@ module Kitchen
         NEWVM
       end
 
+      # The `AdditionalDisks` entry spliced into {#new_vm_ps}.
+      #
+      # Reads the paths {Hyperv#create_additional_disks} recorded, so it is only
+      # meaningful after that has run.
+      #
+      # @return [String, nil] the parameter line, or nil when no additional
+      #   disks are configured
+      # @api private
       def additional_disks
         return if config[:additional_disks].nil?
 
@@ -145,7 +287,11 @@ module Kitchen
         EOH
       end
 
-      # TODO: Report if VM has no IP address instead of silently waiting forever
+      # Script that reads the VM's name, id and IP address.
+      #
+      # @return [String] PowerShell source
+      # @api private
+      # @todo Report if VM has no IP address instead of silently waiting forever
       def vm_details_ps
         <<-DETAILS
 
@@ -153,6 +299,38 @@ module Kitchen
         DETAILS
       end
 
+      # Script that reads the VM's current power state without changing it.
+      #
+      # Unlike {#ensure_vm_running_ps}, this never starts a stopped VM, so it is
+      # safe for `kitchen list --probe`.
+      #
+      # @return [String] PowerShell source
+      # @api private
+      def vm_status_ps
+        <<-STATUS
+
+          Get-VmStatus -Id "#{@state[:id]}" | ConvertTo-Json
+        STATUS
+      end
+
+      # Script that reports whether the Hyper-V PowerShell module is installed.
+      #
+      # @return [String] PowerShell source
+      # @api private
+      def hyperv_module_ps
+        <<-MODULE
+
+          Get-Module -ListAvailable -Name Hyper-V |
+            Select-Object -First 1 |
+            ForEach-Object { [pscustomobject]@{ Name = $_.Name; Version = [string]$_.Version } } |
+            ConvertTo-Json
+        MODULE
+      end
+
+      # Script that forces the VM off and removes it.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def delete_vm_ps
         <<-REMOVE
 
@@ -162,6 +340,10 @@ module Kitchen
         REMOVE
       end
 
+      # Script that assigns the VM a static address once its adapter is up.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def set_vm_ipaddress_ps
         <<-VMIP
 
@@ -178,30 +360,55 @@ module Kitchen
         VMIP
       end
 
+      # Script that resolves the virtual switch to attach the VM to.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def vm_default_switch_ps
         <<-VMSWITCH
           Get-DefaultVMSwitch "#{config[:vm_switch]}" | ConvertTo-Json
         VMSWITCH
       end
 
+      # Script that attaches the configured ISO to the VM's DVD drive.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def mount_vm_iso
         <<-MOUNTISO
           mount-vmiso -id "#{@state[:id]}" -Path #{config[:iso_path]}
         MOUNTISO
       end
 
+      # Script that grows the parent VHD to the configured size.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def resize_vhd
         <<-VMNOTE
           Resize-VHD -Path "#{parent_vhd_path}" -SizeBytes #{config[:resize_vhd]}
         VMNOTE
       end
 
+      # Script that writes the configured note onto the VM.
+      #
+      # @return [String] PowerShell source
+      # @api private
       def set_vm_note
         <<-VMNOTE
           Set-VM -Name (Get-VM | Where-Object{ $_.ID -eq "#{@state[:id]}"}).Name -Note "#{config[:vm_note]}"
         VMNOTE
       end
 
+      # Script that copies a file or directory into the running guest.
+      #
+      # Enables the guest service interface first if it is off, and walks a
+      # directory source file by file since `Copy-VMFile` handles only files.
+      #
+      # @param source [String] path on the Hyper-V host
+      # @param dest [String] path inside the guest
+      # @return [String] PowerShell source
+      # @api private
       def copy_vm_file_ps(source, dest)
         <<-FILECOPY
           Function CopyFile ($VM, [string]$SourcePath, [string]$DestPath) {
@@ -240,6 +447,11 @@ module Kitchen
 
       private
 
+      # Render a Ruby array as a PowerShell array literal.
+      #
+      # @param list [Array<String>, nil] the values
+      # @return [String] e.g. `@("8.8.8.8", "8.8.4.4")`, or `@()` when empty
+      # @api private
       def ruby_array_to_ps_array(list)
         return "@()" if list.nil? || list.empty?