ruby-pwsh 0.10.2 → 0.11.0.rc.1

data/DESIGN.md

@@ -1,70 +0,0 @@
-# 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

@@ -1,54 +0,0 @@
-# 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', '>= 0.77'
-  gem 'rubocop-rspec'
-  gem 'simplecov'
-end
-
-group :development do
-  gem 'github_changelog_generator', '~> 1.15' if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.3.0')
-  gem 'yard'
-end
-
-group :puppet do
-  gem 'pdk', '~> 1.0'
-  if ENV['PUPPET_GEM_VERSION']
-    gem 'puppet', "~> #{ENV['PUPPET_GEM_VERSION']}"
-  else
-    gem 'puppet'
-  end
-end
-
-group :pry do
-  gem 'fuubar'
-
-  if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.4.0')
-    gem 'pry-byebug'
-  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

@@ -1,21 +0,0 @@
-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/Rakefile

@@ -1,188 +0,0 @@
-# frozen_string_literal: true
-
-require 'rubocop/rake_task'
-require 'fileutils'
-require 'github_changelog_generator/task'
-require 'open3'
-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.1.0'
-  config.exclude_labels = ['maint']
-  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
-
-# Executes a command locally.
-#
-# @param command [String] command to execute.
-# @return [Object] the standard out stream.
-def run_local_command(command)
-  stdout, stderr, status = Open3.capture3(command)
-  error_message = "Attempted to run\ncommand:'#{command}'\nstdout:#{stdout}\nstderr:#{stderr}"
-  raise error_message unless status.to_i.zero?
-
-  stdout
-end
-
-# Build the gem
-desc 'Build the gem'
-task :build do
-  gemspec_path = File.join(Dir.pwd, 'ruby-pwsh.gemspec')
-  run_local_command("bundle exec gem build '#{gemspec_path}'")
-end
-
-# Tag the repo with a version in preparation for the release
-#
-# @param :version [String] a semantic version to tag the code with
-# @param :sha [String] the sha at which to apply the version tag
-desc 'Tag the repo with a version in preparation for release'
-task :tag, [:version, :sha] do |_task, args|
-  raise "Invalid version #{args[:version]} - must be like '1.2.3'" unless args[:version] =~ /^\d+\.\d+\.\d+$/
-
-  run_local_command('git fetch upstream')
-  run_local_command("git tag -a #{args[:version]} -m #{args[:version]} #{args[:sha]}")
-  run_local_command('git push upstream --tags')
-end
-
-# Push the built gem to RubyGems
-#
-# @param :path [String] optional, the full or relative path to the built gem to be pushed
-desc 'Push to RubyGems'
-task :push, [:path] do |_task, args|
-  raise 'No discoverable gem for pushing' if Dir.glob("ruby-pwsh*\.gem").empty? && args[:path].nil?
-  raise "No file found at specified path: '#{args[:path]}'" unless File.exist?(args[:path])
-
-  path = args[:path] || File.join(Dir.pwd, Dir.glob("ruby-pwsh*\.gem")[0])
-  run_local_command("bundle exec gem push #{path}")
-end
-
-desc 'Build for Puppet'
-task :build_module do
-  actual_readme_content = File.read('README.md')
-  FileUtils.copy_file('pwshlib.md', 'README.md')
-  # Build
-  run_local_command('pdk build --force')
-  # Cleanup
-  File.open('README.md', 'wb') { |file| file.write(actual_readme_content) }
-end
-
-# Used in vendor_dsc_module
-TAR_LONGLINK = '././@LongLink'
-
-# Vendor a Puppetized DSC Module to spec/fixtures/modules.
-#
-# This is necessary because `puppet module install` fails on modules with
-# long file paths, like xpsdesiredstateconfiguration
-#
-# @param command [String] command to execute.
-# @return [Object] the standard out stream.
-def vendor_dsc_module(name, version, destination)
-  require 'open-uri'
-  require 'rubygems/package'
-  require 'zlib'
-
-  module_uri = "https://forge.puppet.com/v3/files/dsc-#{name}-#{version}.tar.gz"
-  tar_gz_archive = File.expand_path("#{name}.tar.gz", ENV['TEMP'])
-
-  # Download the archive from the forge
-  File.open(tar_gz_archive, 'wb') do |file|
-    file.write(URI.open(module_uri).read) # rubocop:disable Security/Open
-  end
-
-  # Unzip to destination
-  # Taken directly from StackOverflow:
-  # - https://stackoverflow.com/a/19139114
-  Gem::Package::TarReader.new(Zlib::GzipReader.open(tar_gz_archive)) do |tar|
-    dest = nil
-    tar.each do |entry|
-      if entry.full_name == TAR_LONGLINK
-        dest = File.join(destination, entry.read.strip)
-        next
-      end
-      dest ||= File.join(destination, entry.full_name)
-      if entry.directory?
-        File.delete(dest) if File.file?(dest)
-        FileUtils.mkdir_p(dest, mode: entry.header.mode, verbose: false)
-      elsif entry.file?
-        FileUtils.rm_rf(dest) if File.directory?(dest)
-        File.open(dest, 'wb') do |f|
-          f.print(entry.read)
-        end
-        FileUtils.chmod(entry.header.mode, dest, verbose: false)
-      elsif entry.header.typeflag == '2' # Symlink!
-        File.symlink(entry.header.linkname, dest)
-      end
-      dest = nil
-    end
-  end
-
-  # Rename folder to just the module name, as needed by Puppet
-  Dir.glob("#{destination}/*#{name}*").each do |existing_folder|
-    new_folder = File.expand_path(name, destination)
-    FileUtils.mv(existing_folder, new_folder)
-  end
-end
-
-namespace :dsc do
-  namespace :acceptance do
-    desc 'Prep for running DSC acceptance tests'
-    task :spec_prep do
-      # Create the modules fixture folder, if needed
-      modules_folder = File.expand_path('spec/fixtures/modules', File.dirname(__FILE__))
-      FileUtils.mkdir_p(modules_folder) unless Dir.exist?(modules_folder)
-      # symlink the parent folder to the modules folder for puppet
-      symlink_path = File.expand_path('pwshlib', modules_folder)
-      File.symlink(File.dirname(__FILE__), symlink_path) unless Dir.exist?(symlink_path)
-      # Install each of the required modules for acceptance testing
-      # Note: This only works for modules in the dsc namespace on the forge.
-      puppetized_dsc_modules = [
-        { name: 'powershellget', version: '2.2.5-0-1' },
-        { name: 'jeadsc', version: '0.7.2-0-3' },
-        { name: 'xpsdesiredstateconfiguration', version: '9.1.0-0-1' },
-        { name: 'xwebadministration', version: '3.2.0-0-2' },
-        { name: 'accesscontroldsc', version: '1.4.1-0-3' }
-      ]
-      puppetized_dsc_modules.each do |puppet_module|
-        next if Dir.exist?(File.expand_path(puppet_module[:name], modules_folder))
-
-        vendor_dsc_module(puppet_module[:name], puppet_module[:version], modules_folder)
-      end
-    end
-    RSpec::Core::RakeTask.new(:spec) do |t|
-      t.pattern = 'spec/acceptance/dsc/*.rb'
-    end
-  end
-end

data/metadata.json

@@ -1,82 +0,0 @@
-{
-  "name": "puppetlabs-pwshlib",
-  "version": "0.10.2",
-  "author": "puppetlabs",
-  "summary": "Provide library code for interoperating with PowerShell.",
-  "license": "MIT",
-  "source": "https://github.com/puppetlabs/ruby-pwsh",
-  "project_page": "https://github.com/puppetlabs/ruby-pwsh/blob/main/pwshlib.md",
-  "issues_url": "https://github.com/puppetlabs/ruby-pwsh/issues",
-  "dependencies": [
-
-  ],
-  "operatingsystem_support": [
-    {
-      "operatingsystem": "Windows",
-      "operatingsystemrelease": [
-        "2008",
-        "2008 R2",
-        "2012",
-        "2012 R2",
-        "2016",
-        "2019",
-        "7",
-        "8",
-        "10"
-      ]
-    },
-    {
-      "operatingsystem": "CentOS",
-      "operatingsystemrelease": [
-        "7",
-        "8"
-      ]
-    },
-    {
-      "operatingsystem": "Debian",
-      "operatingsystemrelease": [
-        "8",
-        "9",
-        "10"
-      ]
-    },
-    {
-      "operatingsystem": "Fedora",
-      "operatingsystemrelease": [
-        "30",
-        "31"
-      ]
-    },
-    {
-      "operatingsystem": "OSX ",
-      "operatingsystemrelease": [
-        "10.14",
-        "10.15"
-      ]
-    },
-    {
-      "operatingsystem": "RedHat",
-      "operatingsystemrelease": [
-        "7",
-        "8"
-      ]
-    },
-    {
-      "operatingsystem": "Ubuntu",
-      "operatingsystemrelease": [
-        "16.04",
-        "18.04",
-        "20.04"
-      ]
-    }
-  ],
-  "requirements": [
-    {
-      "name": "puppet",
-      "version_requirement": ">= 6.0.0 < 8.0.0"
-    }
-  ],
-  "pdk-version": "1.13.0",
-  "template-url": "pdk-default#1.13.0",
-  "template-ref": "1.13.0-0-g66e1443"
-}

data/pwshlib.md

@@ -1,92 +0,0 @@
-# pwshlib
-
-This module enables you to leverage the `ruby-pwsh` gem to execute PowerShell from within your Puppet providers without having to instantiate and tear down a PowerShell process for each command called.
-It supports Windows PowerShell as well as PowerShell Core - 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.
-
-## Prerequisites
-
-Include `puppetlabs-pwshlib` as a dependency in your module and you can leverage it in your providers by using a requires statement, such as in this example:
-
-```ruby
-require 'puppet/resource_api/simple_provider'
-begin
-  require 'ruby-pwsh'
-rescue LoadError
-  raise 'Could not load the "ruby-pwsh" library; is the dependency module puppetlabs-pwshlib installed in this environment?'
-end
-
-# Implementation for the foo type using the Resource API.
-class Puppet::Provider::Foo::Foo < Puppet::ResourceApi::SimpleProvider
-  def get(context)
-    context.debug("PowerShell Path: #{Pwsh::Manager.powershell_path}")
-    context.debug('Returning pre-canned example data')
-    [
-      {
-        name: 'foo',
-        ensure: 'present',
-      },
-      {
-        name: 'bar',
-        ensure: 'present',
-      },
-    ]
-  end
-
-  def create(context, name, should)
-    context.notice("Creating '#{name}' with #{should.inspect}")
-  end
-
-  def update(context, name, should)
-    context.notice("Updating '#{name}' with #{should.inspect}")
-  end
-
-  def delete(context, name)
-    context.notice("Deleting '#{name}'")
-  end
-end
-```
-
-Aside from adding it as a dependency to your module metadata, you will probably also want to include it in your `.fixtures.yml` file:
-
-```yaml
-fixtures:
-  forge_modules:
-    pwshlib: "puppetlabs/pwshlib"
-```
-
-## Using the Library
-
-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.
-Puppet.debug(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.
-Puppet.debug(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
-Puppet.debug("The PowerShell version of the currently running Manager is #{ps_version}")
-```
-
-For more information, please review the [online reference documentation for the gem](https://rubydoc.info/gems/ruby-pwsh).

data/ruby-pwsh.gemspec

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-lib = File.expand_path('lib', __dir__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'pwsh/version'
-
-Gem::Specification.new do |spec|
-  spec.name          = 'ruby-pwsh'
-  spec.version       = Pwsh::VERSION
-  spec.authors       = ['Puppet, Inc.']
-  spec.email         = ['info@puppet.com']
-
-  spec.summary       = 'PowerShell code manager for ruby.'
-  spec.description   = 'PowerShell code manager for ruby.'
-  spec.homepage      = 'https://github.com/puppetlabs/ruby-pwsh'
-  spec.license       = 'MIT'
-
-  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
-  # to allow pushing to a single host or delete this section to allow pushing to any host.
-  if spec.respond_to?(:metadata)
-
-    spec.metadata['homepage_uri'] = spec.homepage
-    spec.metadata['source_code_uri'] = 'https://github.com/puppetlabs/ruby-pwsh'
-    spec.metadata['changelog_uri'] = 'https://github.com/puppetlabs/ruby-pwsh'
-  else
-    raise 'RubyGems 2.0 or newer is required to protect against ' \
-      'public gem pushes.'
-  end
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  end
-
-  spec.bindir        = 'exe'
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ['lib']
-end