ruby-pwsh 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 45a4e8fcc1b0bf5eba64fc3798038898f082e1f2306523e197de6c801f61c872
+  data.tar.gz: 31817197b1a07056dd1f4e6d9296eec1ceb4a39380244a9d00aa937a4ac76aa6
+SHA512:
+  metadata.gz: 5fd66bd52888d7a52bc262d2f977f6100b723531ee283aff31aec7e95ab9b0605e3fce7dcb94e34d13de4b01d0236a56b49ca60e55148e7df4a7dfee63cd8f2d
+  data.tar.gz: 98668a759b733ddc17651011709c1070ae0b407afb84f4de356ec2b181d8353db0d5b57f1cdc64cf67039c994fb6811c679140a3177ba9e489ba72a3874032d0

data/.gitattributes

@@ -0,0 +1,2 @@
+# Ensure line endings are always LF
+* text eol=lf

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/bin/
+
+# rspec failure tracking
+.rspec_status
+
+Gemfile.local
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,31 @@
+Layout/EndOfLine:
+  Description: Don't enforce CRLF on Windows.
+  Enabled: false
+Metrics/LineLength:
+  Description: People have wide screens, use them.
+  Max: 200
+Metrics/BlockLength:
+  Enabled: false
+Metrics/MethodLength:
+  Enabled: false
+Metrics/ClassLength:
+  Enabled: false
+Metrics/PerceivedComplexity:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/AbcSize:
+  Enabled: false
+
+# requires 2.3's squiggly HEREDOC support, which we can't use, yet
+# see http://www.virtuouscode.com/2016/01/06/about-the-ruby-squiggly-heredoc-syntax/
+Layout/IndentHeredoc:
+  Enabled: false
+# Need to ignore rubocop complaining about the name of the library.
+Naming/FileName:
+  Exclude:
+    - lib/ruby-pwsh.rb
+Style/RescueStandardError:
+  Enabled: false
+Style/ExpandPathArguments:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,25 @@
+---
+dist: bionic
+language: ruby
+cache: bundler
+sudo: true
+before_install:
+  - bundle -v
+  - rm -f Gemfile.lock
+  - gem update --system $RUBYGEMS_VERSION
+  - gem --version
+  - bundle -v
+  - wget -q https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb
+  - sudo dpkg -i packages-microsoft-prod.deb
+  - sudo apt-get update
+  - sudo add-apt-repository universe
+  - sudo apt-get install -y powershell
+  - pwsh -v
+script:
+  - 'bundle exec rake $CHECK'
+rvm:
+  - 2.5.1
+matrix:
+  include:
+  - env: CHECK="rubocop"
+  - env: CHECK='spec'

data/CODEOWNERS

@@ -0,0 +1,2 @@
+# Setting ownership to the modules team
+* @puppetlabs/modules

data/DESIGN.md

@@ -0,0 +1,70 @@
+# PowerShell Manager: Design and Architecture
+
+This gem allows the use of a long-lived manager to which Ruby can send PowerShell invocations and receive the exection output.
+This reduces the overhead time to execute PowerShell commands from seconds to milliseconds because each execution does not need to spin up a PowerShell process, execute a single pipeline, and tear the process down.
+
+The manager operates by instantiating a custom PowerShell host process to which Ruby can then send commands over an IO pipe—
+on Windows machines, named pipes, on Unix/Linux, Unix Domain Sockets.
+
+## Communication Between Ruby and PowerShell Host Process
+
+Communication between Ruby and the PowerShell host process uses binary encoded strings with a [4-byte prefix indicating how long the message is](https://en.wikipedia.org/wiki/Type-length-value).
+The length prefix is a Little Endian encoded 32-bit integer.
+The string being passed is always UTF-8.
+
+Before a command string is sent to the PowerShell host process, a single 1-byte command identifier is sent—
+`0` to tell the process to exit, `1` to tell the process to execute the next incoming string.
+
+The PowerShell code to be executed is always wrapped in the following for execution to standardize behavior inside the PowerShell host process:
+
+```powershell
+$params = @{
+  Code                     = @'
+#{powershell_code}
+'@
+  TimeoutMilliseconds      = #{timeout_ms}
+  WorkingDirectory         = "#{working_dir}"
+  ExecEnvironmentVariables = #{exec_environment_variables}
+}
+
+Invoke-PowerShellUserCode @params
+```
+
+The code itself is placed inside a herestring and the timeout (integer), working directory (string), and environment variables (hash), if any, are passed as well.
+
+![Diagram of communication flow for execution between Ruby and PowerShell manager](./design-comms.png)
+
+### Output
+
+The return from a Ruby command will always include:
+
++ `stdout` from the output streams, as if using `*>&1` to redirect
++ `exitcode` for the exit code of the execution; this will always be `0`, unless an exit code is specified or an exception is _thrown_.
++ `stderr` will always be an empty array.
++ `errormessage` will be the exception message of any thrown exception during execution.
++ `native_stdout` will always be nil.
+
+#### Error Handling
+
+Because PowerShell does not halt execution when an error is encountered, only when an terminating exception is thrown, the manager _also_ continues to execute until it encounters a terminating exception when executing commands.
+This means that `Write-Error` messages will go to the stdout log but will not cause a change in the `exitcode` or populate the `errormessage` field.
+Using `Throw` or any other method of generating a terminating exception _will_ set the `exitcode` to `1` and populate the `errormessage` field.
+
+## Multiple PowerShell Host Processes
+
+Until told otherwise, or they break, or their parent process closes, the instantiated PowerShell host processes will remain alive and waiting for further commands.
+The significantly speeds up the execution of serialized commands, making continual interoperation between Ruby and PowerShell less complex for the developer leveraging this library.
+
+In order to do this, the manager class has a class variable, `@@instances`, which contains a hash of the PowerShell hosts:
+
++ The key is the unique combination of options - path to the executable, flags, and additional options - passed to create the instance.
++ The value is the current state of that instance of the PowerShell host process.
+
+If you attempt to instantiate an instance of the manager using the `instance` method, it will _first_ look to see if the specified manager and host process are already built and alive - if the manager instance does not exist or the host process is dead, _then_ it will spin up a new host process.
+
+In test executions, standup of an instance takes around 1.5 seconds - accessing a pre-existing instance takes thousandths of a second.
+
+## Multithreading
+
+The manager and PowerShell host process are designed to be used single-threadedly with the PowerShell host expecting a single command and returning a single output at a time.
+It does not at this time have additional guarding against being sent commands by multiple processes, but since the handles are unique IDs, this should not happen in practice.

data/Gemfile

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in pwsh.gemspec
+gemspec
+
+group :test do
+  gem 'ffi'
+  gem 'rake', '>= 10.0'
+  gem 'rspec', '~> 3.0'
+  gem 'rspec-collection_matchers', '~> 1.0'
+  gem 'rspec-its', '~> 1.0'
+  gem 'rubocop'
+  gem 'rubocop-rspec'
+  gem 'simplecov'
+end
+
+group :development do
+  # TODO: Use gem instead of git. Section mapping is merged into master, but not yet released
+  gem 'github_changelog_generator', git: 'https://github.com/skywinder/github-changelog-generator.git', ref: '20ee04ba1234e9e83eb2ffb5056e23d641c7a018'
+  gem 'yard'
+end
+
+group :pry do
+  gem 'fuubar'
+
+  if RUBY_VERSION == '1.8.7'
+    gem 'debugger'
+  elsif RUBY_VERSION =~ /^2\.[01]/
+    gem 'byebug', '~> 9.0.0'
+    gem 'pry-byebug'
+  elsif RUBY_VERSION =~ /^2\.[23456789]/
+    gem 'pry-byebug' # rubocop:disable Bundler/DuplicatedGem
+  else
+    gem 'pry-debugger'
+  end
+
+  gem 'pry-stack_explorer'
+end
+
+# Evaluate Gemfile.local and ~/.gemfile if they exist
+extra_gemfiles = [
+  "#{__FILE__}.local",
+  File.join(Dir.home, '.gemfile')
+]
+
+extra_gemfiles.each do |gemfile|
+  eval(File.read(gemfile), binding) if File.file?(gemfile) && File.readable?(gemfile) # rubocop:disable Security/Eval
+end
+# vim: syntax=ruby

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 PuppetLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,69 @@
+# ruby-pwsh
+
+> _The PowerShell gem._
+
+This gem enables you to execute PowerShell from within ruby without having to instantiate and tear down a PowerShell process for each command called.
+It supports Windows PowerShell as well as PowerShell Core (and, soon, _just_ PowerShell) - if you're running *PowerShell v3+, this gem supports you.
+
+The `Manager` class enables you to execute and interoperate with PowerShell from within ruby, leveraging the strengths of both languages as needed.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ruby-pwsh'
+```
+
+And then execute:
+
+```shell
+bundle install
+```
+
+Or install it yourself as:
+
+```shell
+gem install ruby-pwsh
+```
+
+## Usage
+
+Instantiating the manager can be done using some defaults:
+
+```ruby
+# Instantiate the manager for Windows PowerShell, using the default path and arguments
+# Note that this takes a few seconds to instantiate.
+posh = Pwsh::Manager.instance(Pwsh::Manager.powershell_path, Pwsh::Manager.powershell_args)
+# If you try to create another manager with the same arguments it will reuse the existing one.
+ps = Pwsh::Manager.instance(Pwsh::Manager.powershell_path, Pwsh::Manager.powershell_args)
+# Note that this time the return is very fast.
+# We can also use the defaults for PowerShell Core, though these only work if PowerShell is
+# installed to the default paths - if it is installed anywhere else, you'll need to specify
+# the full path to the pwsh executable.
+pwsh = Pwsh::Manager.instance(Pwsh::Manager.pwsh_path, Pwsh::Manager.pwsh_args)
+```
+
+Execution can be done with relatively little additional work - pass the command string you want executed:
+
+```ruby
+# Instantiate the Manager:
+posh = Pwsh::Manager.instance(Pwsh::Manager.powershell_path, Pwsh::Manager.powershell_args)
+# Pretty print the output of `$PSVersionTable` to validate the version of PowerShell running
+# Note that the output is a hash with a few different keys, including stdout.
+pp(posh.execute('$PSVersionTable'))
+# Lets reduce the noise a little and retrieve just the version number:
+# Note: We cast to a string because PSVersion is actually a Version object.
+pp(posh.execute('[String]$PSVersionTable.PSVersion'))
+# We could store this output to a ruby variable if we wanted, for further use:
+ps_version = posh.execute('[String]$PSVersionTable.PSVersion')[:stdout].strip
+pp("The PowerShell version of the currently running Manager is #{ps_version}")
+```
+
+<!-- ## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). -->
+
+## Known Issues

data/Rakefile

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'rubocop/rake_task'
+require 'github_changelog_generator/task'
+require 'pwsh/version'
+require 'rspec/core/rake_task'
+require 'yard'
+
+GitHubChangelogGenerator::RakeTask.new :changelog do |config|
+  config.user = 'puppetlabs'
+  config.project = 'ruby-pwsh'
+  config.future_release = Pwsh::VERSION
+  config.since_tag = '0.0.1'
+  config.exclude_labels = ['maintenance']
+  config.header = "# Change log\n\nAll notable changes to this project will be documented in this file." \
+                  'The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org).'
+  config.add_pr_wo_labels = true
+  config.issues = false
+  config.merge_prefix = '### UNCATEGORIZED PRS; GO LABEL THEM'
+  config.configure_sections = {
+    'Changed' => {
+      'prefix' => '### Changed',
+      'labels' => %w[backwards-incompatible]
+    },
+    'Added' => {
+      'prefix' => '### Added',
+      'labels' => %w[feature enhancement]
+    },
+    'Fixed' => {
+      'prefix' => '### Fixed',
+      'labels' => %w[bugfix]
+    }
+  }
+end
+
+RuboCop::RakeTask.new(:rubocop) do |task|
+  task.options = %w[-D -S -E]
+end
+
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec
+
+YARD::Rake::YardocTask.new do |t|
+end

data/lib/pwsh.rb

@@ -0,0 +1,653 @@
+# frozen_string_literal: false
+
+require 'pwsh/util'
+require 'pwsh/version'
+require 'pwsh/windows_powershell'
+require 'rexml/document'
+require 'securerandom'
+require 'socket'
+require 'open3'
+require 'base64'
+require 'logger'
+
+# Manage PowerShell and Windows PowerShell via ruby
+module Pwsh
+  # Standard errors
+  class Error < StandardError; end
+  # Create an instance of a PowerShell host and manage execution of PowerShell code inside that host.
+  class Manager
+    attr_reader :powershell_command
+    attr_reader :powershell_arguments
+
+    # We actually want this to be a class variable.
+    @@instances = {} # rubocop:disable Style/ClassVars
+
+    # Return the list of currently instantiated instances of the PowerShell Manager
+    # @return [Hash] the list of instantiated instances of the PowerShell Manager, including their params and status.
+    def self.instances
+      @@instances
+    end
+
+    # Returns a set of default options for instantiating a manager
+    #
+    # @return [Hash] the default options for a new manager
+    def self.default_options
+      {
+        debug: false,
+        pipe_timeout: 30
+      }
+    end
+
+    # Return an instance of the manager if one already exists for the specified
+    # options or instantiate a new one if needed
+    #
+    # @param cmd [String] the full path to the PowerShell executable to manage
+    # @param args [Array] the list of additional arguments to pass PowerShell
+    # @param options [Hash] the set of options to set the behavior of the manager, including debug/timeout
+    # @return [] specific instance matching the specified parameters either newly created or previously instantiated
+    def self.instance(cmd, args, options = {})
+      options = default_options.merge!(options)
+
+      key = instance_key(cmd, args, options)
+      manager = @@instances[key]
+
+      if manager.nil? || !manager.alive?
+        # ignore any errors trying to tear down this unusable instance
+        begin
+          manager&.exit
+        rescue
+          nil
+        end
+        @@instances[key] = Manager.new(cmd, args, options)
+      end
+
+      @@instances[key]
+    end
+
+    # Determine whether or not the Win32 Console is enabled
+    #
+    # @return [Bool] true if enabled
+    def self.win32console_enabled?
+      @win32console_enabled ||= defined?(Win32) &&
+                                defined?(Win32::Console) &&
+                                Win32::Console.class == Class
+    end
+
+    # TODO: This thing isn't called anywhere and the variable it sets is never referenced...
+    # Determine whether or not the machine has a compatible version of Windows PowerShell
+    #
+    # @return [Bool] true if Windows PowerShell 3+ is available or 2+ with .NET 3.5SP1
+    # def self.compatible_version_of_windows_powershell?
+    #   @compatible_version_of_powershell ||= Pwsh::WindowsPowerShell.compatible_version?
+    # end
+
+    # Determine whether or not the manager is supported on the machine for Windows PowerShell
+    #
+    # @return [Bool] true if Windows PowerShell is manageable
+    def self.windows_powershell_supported?
+      Pwsh::Util.on_windows? &&
+        Pwsh::WindowsPowerShell.compatible_version? &&
+        !win32console_enabled?
+    end
+
+    # Determine whether or not the manager is supported on the machine for PowerShell 6+
+    #
+    # @return [Bool] true if pwsh is manageable
+    def self.pwsh_supported?
+      !win32console_enabled?
+    end
+
+    # Instantiate a new instance of the PowerShell Manager
+    #
+    # @param cmd [String]
+    # @param args [Array]
+    # @param options [Hash]
+    # @return nil
+    def initialize(cmd, args = [], options = {})
+      @usable = true
+      @powershell_command = cmd
+      @powershell_arguments = args
+
+      raise "Bad configuration for ENV['lib']=#{ENV['lib']} - invalid path" if Pwsh::Util.invalid_directories?(ENV['lib'])
+
+      if Pwsh::Util.on_windows?
+        # Named pipes under Windows will automatically be mounted in \\.\pipe\...
+        # https://github.com/dotnet/corefx/blob/a10890f4ffe0fadf090c922578ba0e606ebdd16c/src/System.IO.Pipes/src/System/IO/Pipes/NamedPipeServerStream.Windows.cs#L34
+        named_pipe_name = "#{SecureRandom.uuid}PsHost"
+        # This named pipe path is Windows specific.
+        pipe_path = "\\\\.\\pipe\\#{named_pipe_name}"
+      else
+        # .Net implements named pipes under Linux etc. as Unix Sockets in the filesystem
+        # Paths that are rooted are not munged within C# Core.
+        # https://github.com/dotnet/corefx/blob/94e9d02ad70b2224d012ac4a66eaa1f913ae4f29/src/System.IO.Pipes/src/System/IO/Pipes/PipeStream.Unix.cs#L49-L60
+        # https://github.com/dotnet/corefx/blob/a10890f4ffe0fadf090c922578ba0e606ebdd16c/src/System.IO.Pipes/src/System/IO/Pipes/NamedPipeServerStream.Unix.cs#L44
+        # https://github.com/dotnet/corefx/blob/a10890f4ffe0fadf090c922578ba0e606ebdd16c/src/System.IO.Pipes/src/System/IO/Pipes/NamedPipeServerStream.Unix.cs#L298-L299
+        named_pipe_name = File.join(Dir.tmpdir, "#{SecureRandom.uuid}PsHost")
+        pipe_path = named_pipe_name
+      end
+      pipe_timeout = options[:pipe_timeout] || self.class.default_options[:pipe_timeout]
+      debug = options[:debug] || self.class.default_options[:debug]
+      native_cmd = Pwsh::Util.on_windows? ? "\"#{cmd}\"" : cmd
+
+      ps_args = args + ['-File', self.class.template_path, "\"#{named_pipe_name}\""]
+      ps_args << '"-EmitDebugOutput"' if debug
+      # @stderr should never be written to as PowerShell host redirects output
+      stdin, @stdout, @stderr, @ps_process = Open3.popen3("#{native_cmd} #{ps_args.join(' ')}")
+      stdin.close
+
+      # Puppet.debug "#{Time.now} #{cmd} is running as pid: #{@ps_process[:pid]}"
+
+      # Wait up to 180 seconds in 0.2 second intervals to be able to open the pipe.
+      # If the pipe_timeout is ever specified as less than the sleep interval it will
+      # never try to connect to a pipe and error out as if a timeout occurred.
+      sleep_interval = 0.2
+      (pipe_timeout / sleep_interval).to_int.times do
+        begin
+          @pipe = if Pwsh::Util.on_windows?
+                    # Pipe is opened in binary mode and must always <- always what??
+                    File.open(pipe_path, 'r+b')
+                  else
+                    UNIXSocket.new(pipe_path)
+                  end
+          break
+        rescue
+          sleep sleep_interval
+        end
+      end
+      if @pipe.nil?
+        # Tear down and kill the process if unable to connect to the pipe; failure to do so
+        # results in zombie processes being left after the puppet run. We discovered that
+        # closing @ps_process via .kill instead of using this method actually kills the
+        # watcher and leaves an orphaned process behind. Failing to close stdout and stderr
+        # also leaves clutter behind, so explicitly close those too.
+        @stdout.close unless @stdout.closed?
+        @stderr.close unless @stderr.closed?
+        Process.kill('KILL', @ps_process[:pid]) if @ps_process.alive?
+        raise "Failure waiting for PowerShell process #{@ps_process[:pid]} to start pipe server"
+      end
+      # Puppet.debug "#{Time.now} PowerShell initialization complete for pid: #{@ps_process[:pid]}"
+
+      at_exit { exit }
+    end
+
+    # Return whether or not the manager is running, usable, and the I/O streams remain open.
+    #
+    # @return [Bool] true if manager is in working state
+    def alive?
+      # powershell process running
+      @ps_process.alive? &&
+        # explicitly set during a read / write failure, like broken pipe EPIPE
+        @usable &&
+        # an explicit failure state might not have been hit, but IO may be closed
+        self.class.stream_valid?(@pipe) &&
+        self.class.stream_valid?(@stdout) &&
+        self.class.stream_valid?(@stderr)
+    end
+
+    # Run specified powershell code via the manager
+    #
+    # @param powershell_code [String]
+    # @param timeout_ms [Int]
+    # @param working_dir [String]
+    # @param environment_variables [Hash]
+    # @return [Hash] Hash containing exitcode, stderr, native_stdout and stdout
+    def execute(powershell_code, timeout_ms = nil, working_dir = nil, environment_variables = [])
+      code = make_ps_code(powershell_code, timeout_ms, working_dir, environment_variables)
+      # err is drained stderr pipe (not captured by redirection inside PS)
+      # or during a failure, a Ruby callstack array
+      out, native_stdout, err = exec_read_result(code)
+
+      # an error was caught during execution that has invalidated any results
+      return { exitcode: -1, stderr: err } if out.nil? && !@usable
+
+      out[:exitcode] = out[:exitcode].to_i unless out[:exitcode].nil?
+      # If err contains data it must be "real" stderr output
+      # which should be appended to what PS has already captured
+      out[:stderr] = out[:stderr].nil? ? [] : [out[:stderr]]
+      out[:stderr] += err unless err.nil?
+      out[:native_stdout] = native_stdout
+
+      out
+    end
+
+    # TODO: Is this needed in the code manager? When brought into the module, should this be
+    #       added as helper code leveraging this gem?
+    # Executes PowerShell code using the settings from a populated Puppet Exec Resource Type
+    # def execute_resource(powershell_code, working_dir, timeout_ms, environment)
+    #   working_dir = resource[:cwd]
+    #   if (!working_dir.nil?)
+    #     fail "Working directory '#{working_dir}' does not exist" unless File.directory?(working_dir)
+    #   end
+    #   timeout_ms = resource[:timeout].nil? ? nil : resource[:timeout] * 1000
+    #   environment_variables = resource[:environment].nil? ? [] : resource[:environment]
+
+    #   result = execute(powershell_code, timeout_ms, working_dir, environment_variables)
+
+    #   stdout     = result[:stdout]
+    #   native_out = result[:native_out]
+    #   stderr     = result[:stderr]
+    #   exit_code  = result[:exit_code]
+
+    #   # unless stderr.nil?
+    #   #   stderr.each { |e| Puppet.debug "STDERR: #{e.chop}" unless e.empty? }
+    #   # end
+
+    #   # Puppet.debug "STDERR: #{result[:errormessage]}" unless result[:errormessage].nil?
+
+    #   output = Puppet::Util::Execution::ProcessOutput.new(stdout.to_s + native_out.to_s, exit_code)
+
+    #   return output, output
+    # end
+
+    # Tear down the instance of the manager, shutting down the pipe and process.
+    #
+    # @return nil
+    def exit
+      @usable = false
+
+      # Puppet.debug "Pwsh exiting..."
+
+      # Ask PowerShell pipe server to shutdown if its still running
+      # rather than expecting the pipe.close to terminate it
+      begin
+        write_pipe(pipe_command(:exit)) unless @pipe.closed?
+      rescue
+        nil
+      end
+
+      # Pipe may still be open, but if stdout / stderr are deat the PS
+      # process is in trouble and will block forever on a write to the
+      # pipe. It's safer to close pipe on the Ruby side, which gracefully
+      # shuts down the PS side.
+      @pipe.close   unless @pipe.closed?
+      @stdout.close unless @stdout.closed?
+      @stderr.close unless @stderr.closed?
+
+      # Wait up to 2 seconds for the watcher thread to full exit
+      @ps_process.join(2)
+    end
+
+    # Return the path to the bootstrap template
+    #
+    # @return [String] full path to the bootstrap template
+    def self.template_path
+      # A PowerShell -File compatible path to bootstrap the instance
+      path = File.expand_path('../templates', __FILE__)
+      path = File.join(path, 'init.ps1').gsub('/', '\\')
+      "\"#{path}\""
+    end
+
+    # Return the block of code to be run by the manager with appropriate settings
+    #
+    # @param powershell_code [String] the actual PowerShell code you want to run
+    # @param timeout_ms [Int] the number of milliseconds to wait for the command to run
+    # @param working_dir [String] the working directory for PowerShell to execute from within
+    # @param environment_variables [Array] Any overrides for environment variables you want to specify
+    # @return [String] PowerShell code to be executed via the manager with appropriate params per config.
+    def make_ps_code(powershell_code, timeout_ms = nil, working_dir = nil, environment_variables = [])
+      begin
+        # Zero timeout is a special case. Other modules sometimes treat this
+        # as an infinite timeout. We don't support infinite, so for the case
+        # of a user specifying zero, we sub in the default value of 300s.
+        timeout_ms = 300 * 1000 if timeout_ms.zero?
+
+        timeout_ms = Integer(timeout_ms)
+
+        # Lower bound protection. The polling resolution is only 50ms.
+        timeout_ms = 50 if timeout_ms < 50
+      rescue
+        timeout_ms = 300 * 1000
+      end
+
+      # Environment array firstly needs to be parsed and converted into a hashtable.
+      # And then the values passed in need to be converted to a PowerShell Hashtable.
+      #
+      # Environment parsing is based on the puppet exec equivalent code
+      # https://github.com/puppetlabs/puppet/blob/a9f77d71e992fc2580de7705847e31264e0fbebe/lib/puppet/provider/exec.rb#L35-L49
+      environment = {}
+      if (envlist = environment_variables)
+        envlist = [envlist] unless envlist.is_a? Array
+        envlist.each do |setting|
+          if setting =~ /^(\w+)=((.|\n)+)$/
+            env_name = Regexp.last_match(1)
+            value    = Regexp.last_match(2)
+            if environment.include?(env_name) || environment.include?(env_name.to_sym)
+              # Puppet.warning("Overriding environment setting '#{env_name}' with '#{value}'")
+            end
+            environment[env_name] = value
+          else # rubocop:disable Style/EmptyElse
+            # TODO: Implement logging
+            # Puppet.warning("Cannot understand environment setting #{setting.inspect}")
+          end
+        end
+      end
+      # Convert the Ruby Hashtable into PowerShell syntax
+      exec_environment_variables = '@{'
+      unless environment.empty?
+        environment.each do |name, value|
+          # PowerShell escapes single quotes inside a single quoted string by just adding
+          # another single quote i.e. a value of foo'bar turns into 'foo''bar' when single quoted.
+          ps_name  = name.gsub('\'', '\'\'')
+          ps_value = value.gsub('\'', '\'\'')
+          exec_environment_variables += " '#{ps_name}' = '#{ps_value}';"
+        end
+      end
+      exec_environment_variables += '}'
+
+      # PS Side expects Invoke-PowerShellUserCode is always the return value here
+      # TODO: Refactor to use <<~ as soon as we can :sob:
+      <<-CODE
+$params = @{
+  Code                     = @'
+#{powershell_code}
+'@
+  TimeoutMilliseconds      = #{timeout_ms}
+  WorkingDirectory         = "#{working_dir}"
+  ExecEnvironmentVariables = #{exec_environment_variables}
+}
+
+Invoke-PowerShellUserCode @params
+      CODE
+    end
+
+    # Default arguments for running Windows PowerShell via the manager
+    #
+    # @return [Array[String]] array of command flags to pass Windows PowerShell
+    def self.powershell_args
+      ps_args = ['-NoProfile', '-NonInteractive', '-NoLogo', '-ExecutionPolicy', 'Bypass']
+      ps_args << '-Command' unless windows_powershell_supported?
+
+      ps_args
+    end
+
+    # The path to Windows PowerShell on the system
+    #
+    # @return [String] the absolute path to the PowerShell executable. Returns 'powershell.exe' if no more specific path found.
+    def self.powershell_path
+      if File.exist?("#{ENV['SYSTEMROOT']}\\sysnative\\WindowsPowershell\\v1.0\\powershell.exe")
+        "#{ENV['SYSTEMROOT']}\\sysnative\\WindowsPowershell\\v1.0\\powershell.exe"
+      elsif File.exist?("#{ENV['SYSTEMROOT']}\\system32\\WindowsPowershell\\v1.0\\powershell.exe")
+        "#{ENV['SYSTEMROOT']}\\system32\\WindowsPowershell\\v1.0\\powershell.exe"
+      else
+        'powershell.exe'
+      end
+    end
+
+    # Retrieves the absolute path to pwsh
+    #
+    # @return [String] the absolute path to the found pwsh executable. Returns nil when it does not exist
+    def self.pwsh_path(additional_paths = [])
+      # Environment variables on Windows are not case sensitive however ruby hash keys are.
+      # Convert all the key names to upcase so we can be sure to find PATH etc.
+      # Also while ruby can have difficulty changing the case of some UTF8 characters, we're
+      # only going to use plain ASCII names so this is safe.
+      current_path = Pwsh::Util.on_windows? ? ENV.select { |k, _| k.upcase == 'PATH' }.values[0] : ENV['PATH']
+      current_path = '' if current_path.nil?
+
+      # Prefer any additional paths
+      # TODO: Should we just use arrays by now instead of appending strings?
+      search_paths = additional_paths.empty? ? current_path : additional_paths.join(File::PATH_SEPARATOR) + File::PATH_SEPARATOR + current_path
+
+      # If we're on Windows, try the default installation locations as a last resort.
+      # https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-core-on-windows?view=powershell-6#msi
+      if Pwsh::Util.on_windows?
+        # TODO: What about PS 7? or 8?
+        # TODO: Need to check on French/Turkish windows if ENV['PROGRAMFILES'] parses UTF8 names correctly
+        # TODO: Need to ensure ENV['PROGRAMFILES'] is case insensitive, i.e. ENV['PROGRAMFiles'] should also resolve on Windows
+        search_paths += ";#{ENV['PROGRAMFILES']}\\PowerShell\\6" \
+                        ";#{ENV['PROGRAMFILES(X86)']}\\PowerShell\\6"
+      end
+      raise 'No paths discovered to search for Powershell!' if search_paths.split(File::PATH_SEPARATOR).empty?
+
+      pwsh_paths = []
+      # TODO: THis could probably be done better, but it works!
+      if Pwsh::Util.on_windows?
+        search_paths.split(File::PATH_SEPARATOR).each do |path|
+          pwsh_paths << File.join(path, 'pwsh.exe') if File.exist?(File.join(path, 'pwsh.exe'))
+        end
+      else
+        search_paths.split(File::PATH_SEPARATOR).each do |path|
+          pwsh_paths << File.join(path, 'pwsh') if File.exist?(File.join(path, 'pwsh'))
+        end
+      end
+
+      # TODO: not sure about nil? but .empty? is MethodNotFound on nil
+      raise 'No pwsh discovered!' if pwsh_paths.nil? || pwsh_paths.empty?
+
+      pwsh_paths[0]
+    end
+
+    # Default arguments for running PowerShell 6+ via the manager
+    #
+    # @return [Array[String]] array of command flags to pass PowerShell 6+
+    def self.pwsh_args
+      ['-NoProfile', '-NonInteractive', '-NoLogo', '-ExecutionPolicy', 'Bypass']
+    end
+
+    # The unique key for a given manager as determined by the full path to
+    # the executable, the arguments to pass to the executable, and the options
+    # specified for the manager; this enables the code to reuse an existing
+    # manager if the same path, arguments, and options are specified.
+    #
+    # @return[String] Unique string representing the manager instance.
+    def self.instance_key(cmd, args, options)
+      cmd + args.join(' ') + options[:debug].to_s
+    end
+
+    # Return whether or not a particular stream is valid and readable
+    #
+    # @return [Bool] true if stream is readable and open
+    def self.readable?(stream, timeout = 0.5)
+      raise Errno::EPIPE unless stream_valid?(stream)
+
+      read_ready = IO.select([stream], [], [], timeout)
+      read_ready && stream == read_ready[0][0] && !stream.eof?
+    end
+
+    # When a stream has been closed by handle, but Ruby still has a file
+    # descriptor for it, it can be tricky to detemine that it's actually
+    # dead. The .fileno will still return an int, and calling get_osfhandle
+    # against it returns what the CRT thinks is a valid Windows HANDLE value,
+    # but that may no longer exist.
+    #
+    # @return [Bool] true if stream is open and operational
+    def self.stream_valid?(stream)
+      # When a stream is closed, it's obviously invalid, but Ruby doesn't always know
+      !stream.closed? &&
+        # So calling stat will yield and EBADF when underlying OS handle is bad
+        # as this resolves to a HANDLE and then calls the Windows API
+        !stream.stat.nil?
+    # Any exceptions mean the stream is dead
+    rescue
+      false
+    end
+
+    # The manager sends a 4-byte integer representing the number
+    # of bytes to read for the incoming string. This method reads
+    # that prefix and then reads the specified number of bytes.
+    # Mutates the given bytes, removing the length prefixed value.
+    #
+    # @return [String] The UTF-8 encoded string containing the payload
+    def self.read_length_prefixed_string!(bytes)
+      # 32 bit integer in Little Endian format
+      length = bytes.slice!(0, 4).unpack('V').first
+      return nil if length.zero?
+
+      bytes.slice!(0, length).force_encoding(Encoding::UTF_8)
+    end
+
+    # Takes a given input byte-stream from PowerShell, length-prefixed,
+    # and reads the key-value pairs from that output until all the
+    # information is retrieved. Mutates the given bytes.
+    #
+    # @return [Hash] String pairs representing the information passed
+    def self.ps_output_to_hash!(bytes)
+      hash = {}
+
+      hash[read_length_prefixed_string!(bytes).to_sym] = read_length_prefixed_string!(bytes) until bytes.empty?
+
+      hash
+    end
+
+    # This is the command that the ruby process will send to the PowerShell
+    # process and utilizes a 1 byte command identifier
+    #   0 - Exit
+    #   1 - Execute
+    #
+    # @return[String] Single byte representing the specified command
+    def pipe_command(command)
+      case command
+      when :exit
+        "\x00"
+      when :execute
+        "\x01"
+      end
+    end
+
+    # Take a given string and prefix it with a 4-byte length and encode for sending
+    # to the PowerShell manager.
+    # Data format is:
+    #   4 bytes - Little Endian encoded 32-bit integer length of string
+    #             Intel CPUs are little endian, hence the .NET Framework typically is
+    # variable length - UTF8 encoded string bytes
+    #
+    # @return[String] A binary encoded string prefixed with a 4-byte length identifier
+    def length_prefixed_string(data)
+      msg = data.encode(Encoding::UTF_8)
+      # https://ruby-doc.org/core-1.9.3/Array.html#method-i-pack
+      [msg.bytes.length].pack('V') + msg.force_encoding(Encoding::BINARY)
+    end
+
+    # Writes binary-encoded data to the PowerShell manager process via the pipe.
+    #
+    # @return nil
+    def write_pipe(input)
+      # For Compat with Ruby 2.1 and lower, it's important to use syswrite and
+      # not write - otherwise, the pipe breaks after writing 1024 bytes.
+      written = @pipe.syswrite(input)
+      @pipe.flush
+
+      if written != input.length # rubocop:disable Style/GuardClause
+        msg = "Only wrote #{written} out of #{input.length} expected bytes to PowerShell pipe"
+        raise Errno::EPIPE.new, msg
+      end
+    end
+
+    # Read output from the PowerShell manager process via the pipe.
+    #
+    # @param pipe [IO] I/O Pipe to read from
+    # @param timeout [Float] The number of seconds to wait for the pipe to be readable
+    # @yield [String] a binary encoded string chunk
+    # @return nil
+    def read_from_pipe(pipe, timeout = 0.1, &_block)
+      if self.class.readable?(pipe, timeout)
+        l = pipe.readpartial(4096)
+        # Puppet.debug "#{Time.now} PIPE> #{l}"
+        # Since readpartial may return a nil at EOF, skip returning that value
+        yield l unless l.nil?
+      end
+
+      nil
+    end
+
+    # Read from a specified pipe for as long as the signal is locked and
+    # the pipe is readable. Then return the data as an array of UTF-8 strings.
+    #
+    # @param pipe [IO] the I/O pipe to read
+    # @param signal [Mutex] the signal to wait for whilst reading data
+    # @return [Array] An empty array if no data read or an array wrapping a single UTF-8 string if output received.
+    def drain_pipe_until_signaled(pipe, signal)
+      output = []
+
+      read_from_pipe(pipe) { |s| output << s } while signal.locked?
+
+      # There's ultimately a bit of a race here
+      # Read one more time after signal is received
+      read_from_pipe(pipe, 0) { |s| output << s } while self.class.readable?(pipe)
+
+      # String has been binary up to this point, so force UTF-8 now
+      output == [] ? [] : [output.join('').force_encoding(Encoding::UTF_8)]
+    end
+
+    # Open threads and pipes to read stdout and stderr from the PowerShell manager,
+    # then continue to read data from the manager until either all data is returned
+    # or an error interrupts the normal flow, then return that data.
+    #
+    # @return [Array] Array of three strings representing the output, native stdout, and stderr
+    def read_streams
+      pipe_done_reading = Mutex.new
+      pipe_done_reading.lock
+      # TODO: Uncomment again when implementing logging
+      # start_time = Time.now
+
+      stdout_reader = Thread.new { drain_pipe_until_signaled(@stdout, pipe_done_reading) }
+      stderr_reader = Thread.new { drain_pipe_until_signaled(@stderr, pipe_done_reading) }
+
+      pipe_reader = Thread.new(@pipe) do |pipe|
+        # Read a Little Endian 32-bit integer for length of response
+        expected_response_length = pipe.sysread(4).unpack('V').first
+
+        next nil if expected_response_length.zero?
+
+        # Reads the expected bytes as a binary string or fails
+        buffer = ''
+        # sysread may not return all of the requested bytes due to buffering or the
+        # underlying IO system. Keep reading from the pipe until all the bytes are read.
+        loop do
+          buffer.concat(pipe.sysread(expected_response_length - buffer.length))
+          break if buffer.length >= expected_response_length
+        end
+        buffer
+      end
+
+      # Puppet.debug "Waited #{Time.now - start_time} total seconds."
+
+      # Block until sysread has completed or errors
+      begin
+        output = pipe_reader.value
+        output = self.class.ps_output_to_hash!(output) unless output.nil?
+      ensure
+        # Signal stdout / stderr readers via Mutex so that
+        # Ruby doesn't crash waiting on an invalid event.
+        pipe_done_reading.unlock
+      end
+
+      # Given redirection on PowerShell side, this should always be empty
+      stdout = stdout_reader.value
+
+      [
+        output,
+        stdout == [] ? nil : stdout.join(''), # native stdout
+        stderr_reader.value                   # native stderr
+      ]
+    ensure
+      # Failsafe if the prior unlock was never reached / Mutex wasn't unlocked
+      pipe_done_reading.unlock if pipe_done_reading.locked?
+      # Wait for all non-nil threads to see mutex unlocked and finish
+      [pipe_reader, stdout_reader, stderr_reader].compact.each(&:join)
+    end
+
+    # Executes PowerShell code over the PowerShell manager and returns the results.
+    #
+    # @param powershell_code [String] The PowerShell code to execute via the manager
+    # @return [Array] Array of three strings representing the output, native stdout, and stderr
+    def exec_read_result(powershell_code)
+      write_pipe(pipe_command(:execute))
+      write_pipe(length_prefixed_string(powershell_code))
+      read_streams
+    # If any pipes are broken, the manager is totally hosed
+    # Bad file descriptors mean closed stream handles
+    # EOFError is a closed pipe (could be as a result of tearing down process)
+    # Errno::ECONNRESET is a closed unix domain socket (could be as a result of tearing down process)
+    rescue Errno::EPIPE, Errno::EBADF, EOFError, Errno::ECONNRESET => e
+      @usable = false
+      [nil, nil, [e.inspect, e.backtrace].flatten]
+    # Catch closed stream errors specifically
+    rescue IOError => e
+      raise unless e.message.start_with?('closed stream')
+
+      @usable = false
+      [nil, nil, [e.inspect, e.backtrace].flatten]
+    end
+  end
+end