ruby-pwsh 0.1.0 → 0.5.0

data/lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_functions.ps1

@@ -0,0 +1,120 @@
+function new-pscredential {
+    [CmdletBinding()]
+    param (
+        [parameter(Mandatory = $true,
+            ValueFromPipelineByPropertyName = $true)]
+        [string]
+        $user,
+
+        [parameter(Mandatory = $true,
+            ValueFromPipelineByPropertyName = $true)]
+        [string]
+        $password
+    )
+
+    $secpasswd = ConvertTo-SecureString $password -AsPlainText -Force
+    $credentials = New-Object System.Management.Automation.PSCredential ($user, $secpasswd)
+    return $credentials
+}
+
+Function ConvertTo-CanonicalResult {
+  [CmdletBinding()]
+  param(
+      [Parameter(Mandatory, Position = 1)]
+      [psobject]
+      $Result,
+
+      [Parameter(DontShow)]
+      [string]
+      $PropertyPath,
+
+      [Parameter(DontShow)]
+      [int]
+      $RecursionLevel = 0
+  )
+
+  $MaxDepth = 5
+  $CimInstancePropertyFilter = { $_.Definition -match 'CimInstance' -and $_.Name -ne 'PSDscRunAsCredential' }
+
+  # Get the properties which are/aren't Cim instances
+  $ResultObject = @{ }
+  $ResultPropertyList = $Result | Get-Member -MemberType Property | Where-Object { $_.Name -ne 'PSComputerName' }
+  $CimInstanceProperties = $ResultPropertyList | Where-Object -FilterScript $CimInstancePropertyFilter
+
+  foreach ($Property in $ResultPropertyList) {
+      $PropertyName = $Property.Name
+      if ($Property -notin $CimInstanceProperties) {
+          $Value = $Result.$PropertyName
+          if ($PropertyName -eq 'Ensure' -and [string]::IsNullOrEmpty($Result.$PropertyName)) {
+              # Just set 'Present' since it was found /shrug
+              # If the value IS listed as absent, don't update it unless you want flapping
+              $Value = 'Present'
+          }
+          else {
+              if ($Value -is [string] -or $value -is [string[]]) {
+                  $Value = $Value
+              }
+
+              if ($Value.Count -eq 1 -and $Property.Definition -match '\\[\\]') {
+                  $Value = @($Value)
+              }
+          }
+      }
+      elseif ($null -eq $Result.$PropertyName) {
+          if ($Property -match 'InstanceArray') {
+              $Value = @()
+          }
+          else {
+              $Value = $null
+          }
+      }
+      else {
+          # Looks like a nested CIM instance, recurse if we're not too deep in already.
+          $RecursionLevel++
+
+          if ($PropertyPath -eq [string]::Empty) {
+              $PropertyPath = $PropertyName
+          }
+          else {
+              $PropertyPath = "$PropertyPath.$PropertyName"
+          }
+
+          if ($RecursionLevel -gt $MaxDepth) {
+              # Give up recursing more than this
+              return $Result.ToString()
+          }
+
+          $Value = foreach ($item in $Result.$PropertyName) {
+              ConvertTo-CanonicalResult -Result $item -PropertyPath $PropertyPath -RecursionLevel ($RecursionLevel + 1) -WarningAction Continue
+          }
+
+          # The cim instance type is the last component of the type Name
+          # We need to return this for ruby to compare the result hashes
+          # We do NOT need it for the top-level properties as those are defined in the type
+          If ($RecursionLevel -gt 1 -and ![string]::IsNullOrEmpty($Value) ) {
+              # If there's multiple instances, you need to add the type to each one, but you
+              # need to specify only *one* name, otherwise things end up *very* broken.
+              if ($Value.GetType().Name -match '\[\]') {
+                  $Value | ForEach-Object -Process {
+                      $_.cim_instance_type = $Result.$PropertyName.CimClass.CimClassName[0]
+                  }
+              } else {
+                  $Value.cim_instance_type = $Result.$PropertyName.CimClass.CimClassName
+                  # Ensure that, if it should be an array, it is
+                  if ($Result.$PropertyName.GetType().Name -match '\[\]') {
+                      $Value = @($Value)
+                  }
+              }
+          }
+      }
+
+      if ($Property.Definition -match 'InstanceArray') {
+          if ($Value.Count -lt 2) { $Value = @($Value) }
+      }
+
+      $ResultObject.$PropertyName = $Value
+  }
+
+  # Output the final result
+  $ResultObject
+}

data/lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_postscript.ps1

@@ -0,0 +1,23 @@
+Try {
+  $Result = Invoke-DscResource @InvokeParams
+} catch {
+  $Response.errormessage   = $_.Exception.Message
+  return ($Response | ConvertTo-Json -Compress)
+}
+
+# keep the switch for when Test passes back changed properties
+Switch ($invokeParams.Method) {
+  'Test' {
+    $Response.indesiredstate = $Result.InDesiredState
+    return ($Response | ConvertTo-Json -Compress)
+  }
+  'Set' {
+    $Response.indesiredstate = $true
+    $Response.rebootrequired = $Result.RebootRequired
+    return ($Response | ConvertTo-Json -Compress)
+  }
+  'Get' {
+    $CanonicalizedResult = ConvertTo-CanonicalResult -Result $Result
+    return ($CanonicalizedResult | ConvertTo-Json -Compress -Depth 10)
+  }
+}

data/lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_preamble.ps1

@@ -0,0 +1,8 @@
+$script:ErrorActionPreference = 'Stop'
+$script:WarningPreference = 'SilentlyContinue'
+
+$response = @{
+    indesiredstate = $false
+    rebootrequired = $false
+    errormessage   = ''
+}

data/lib/pwsh.rb

@@ -54,7 +54,7 @@ module Pwsh
       if manager.nil? || !manager.alive?
         # ignore any errors trying to tear down this unusable instance
         begin
-          manager&.exit
+          manager.exit unless manager.nil? # rubocop:disable Style/SafeNavigation
         rescue
           nil
         end
@@ -117,6 +117,7 @@ module Pwsh
         # This named pipe path is Windows specific.
         pipe_path = "\\\\.\\pipe\\#{named_pipe_name}"
       else
+        require 'tmpdir'
         # .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
@@ -470,7 +471,7 @@ Invoke-PowerShellUserCode @params
     # @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
+      length = bytes.slice!(0, 4).unpack1('V')
       return nil if length.zero?
 
       bytes.slice!(0, length).force_encoding(Encoding::UTF_8)
@@ -585,7 +586,7 @@ Invoke-PowerShellUserCode @params
 
       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
+        expected_response_length = pipe.sysread(4).unpack1('V')
 
         next nil if expected_response_length.zero?
 

data/lib/pwsh/util.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Manage PowerShell and Windows PowerShell via ruby
 module Pwsh
   # Various helper methods
   module Util
@@ -11,7 +12,7 @@ module Pwsh
     def on_windows?
       # Ruby only sets File::ALT_SEPARATOR on Windows and the Ruby standard
       # library uses that to test what platform it's on.
-      !!File::ALT_SEPARATOR # rubocop:disable Style/DoubleNegation
+      !!File::ALT_SEPARATOR
     end
 
     # Verify paths specified are valid directories which exist.
@@ -29,6 +30,116 @@ module Pwsh
 
       invalid_paths
     end
+
+    # Return a string or symbol converted to snake_case
+    #
+    # @return [String] snake_cased string
+    def snake_case(object)
+      # Implementation copied from: https://github.com/rubyworks/facets/blob/master/lib/core/facets/string/snakecase.rb
+      # gsub(/::/, '/').
+      should_symbolize = object.is_a?(Symbol)
+      raise "snake_case method only handles strings and symbols, passed a #{object.class}: #{object}" unless should_symbolize || object.is_a?(String)
+
+      text = object.to_s
+                   .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                   .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                   .tr('-', '_')
+                   .gsub(/\s/, '_')
+                   .gsub(/__+/, '_')
+                   .downcase
+      should_symbolize ? text.to_sym : text
+    end
+
+    # Iterate through a hashes keys, snake_casing them
+    #
+    # @return [Hash] Hash with all keys snake_cased
+    def snake_case_hash_keys(object)
+      snake_case_proc = proc { |key| snake_case(key) }
+      apply_key_mutator(object, snake_case_proc)
+    end
+
+    # Return a string or symbol converted to PascalCase
+    #
+    # @return [String] PascalCased string
+    def pascal_case(object)
+      should_symbolize = object.is_a?(Symbol)
+      raise "snake_case method only handles strings and symbols, passed a #{object.class}: #{object}" unless should_symbolize || object.is_a?(String)
+
+      # Break word boundaries to snake case first
+      text = snake_case(object.to_s).split('_').collect(&:capitalize).join
+      should_symbolize ? text.to_sym : text
+    end
+
+    # Iterate through a hashes keys, PascalCasing them
+    #
+    # @return [Hash] Hash with all keys PascalCased
+    def pascal_case_hash_keys(object)
+      pascal_case_proc = proc { |key| pascal_case(key) }
+      apply_key_mutator(object, pascal_case_proc)
+    end
+
+    # Ensure that quotes inside a passed string will continue to be passed
+    #
+    # @return [String] the string with quotes escaped
+    def escape_quotes(text)
+      text.gsub("'", "''")
+    end
+
+    # Ensure that all keys in a hash are symbols, not strings.
+    #
+    # @return [Hash] a hash whose keys have been converted to symbols.
+    def symbolize_hash_keys(object)
+      symbolize_proc = proc(&:to_sym)
+      apply_key_mutator(object, symbolize_proc)
+    end
+
+    def apply_key_mutator(object, proc)
+      return object.map { |item| apply_key_mutator(item, proc) } if object.is_a?(Array)
+      return object unless object.is_a?(Hash)
+
+      modified_hash = {}
+      object.each do |key, value|
+        modified_hash[proc.call(key)] = apply_key_mutator(value, proc)
+      end
+      modified_hash
+    end
+
+    private_class_method :apply_key_mutator
+
+    # Convert a ruby value into a string to be passed along to PowerShell for interpolation in a command
+    # Handles:
+    # - Strings
+    # - Numbers
+    # - Booleans
+    # - Symbols
+    # - Arrays
+    # - Hashes
+    #
+    # @return [String] representation of the value for interpolation
+    def format_powershell_value(object)
+      if %i[true false].include?(object) || %w[trueclass falseclass].include?(object.class.name.downcase) # rubocop:disable Lint/BooleanSymbol
+        "$#{object}"
+      elsif object.class.name == 'Symbol' || object.class.ancestors.include?(Numeric)
+        object.to_s
+      elsif object.class.name == 'String'
+        "'#{escape_quotes(object)}'"
+      elsif object.class.name == 'Array'
+        '@(' + object.collect { |item| format_powershell_value(item) }.join(', ') + ')'
+      elsif object.class.name == 'Hash'
+        '@{' + object.collect { |k, v| format_powershell_value(k) + ' = ' + format_powershell_value(v) }.join('; ') + '}'
+      else
+        raise "unsupported type #{object.class} of value '#{object}'"
+      end
+    end
+
+    # Return the representative string of a PowerShell hash for a custom object property to be used in selecting or filtering.
+    # The script block for the expression must be passed as the string you want interpolated into the hash; this method does
+    # not do any of the additional work of interpolation for you as the type sits inside a code block inside a hash.
+    #
+    # @return [String] representation of a PowerShell hash with the keys 'Name' and 'Expression'
+    def custom_powershell_property(name, expression)
+      "@{Name = '#{name}'; Expression = {#{expression}}}"
+    end
   end
 end
 

data/lib/pwsh/version.rb

@@ -2,5 +2,5 @@
 
 module Pwsh
   # The version of the ruby-pwsh gem
-  VERSION = '0.1.0'
+  VERSION = '0.5.0'
 end

data/metadata.json

@@ -0,0 +1,85 @@
+{
+  "name": "puppetlabs-pwshlib",
+  "version": "0.4.1",
+  "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/master/pwshlib.md",
+  "issues_url": "https://github.com/puppetlabs/ruby-pwsh/issues",
+  "dependencies": [
+
+  ],
+  "operatingsystem_support": [
+    {
+      "operatingsystem": "CentOS",
+      "operatingsystemrelease": [
+        "7"
+      ]
+    },
+    {
+      "operatingsystem": "OracleLinux",
+      "operatingsystemrelease": [
+        "7"
+      ]
+    },
+    {
+      "operatingsystem": "RedHat",
+      "operatingsystemrelease": [
+        "8"
+      ]
+    },
+    {
+      "operatingsystem": "Scientific",
+      "operatingsystemrelease": [
+        "7"
+      ]
+    },
+    {
+      "operatingsystem": "Debian",
+      "operatingsystemrelease": [
+        "9"
+      ]
+    },
+    {
+      "operatingsystem": "Ubuntu",
+      "operatingsystemrelease": [
+        "18.04"
+      ]
+    },
+    {
+      "operatingsystem": "windows",
+      "operatingsystemrelease": [
+        "2019",
+        "10"
+      ]
+    },
+    {
+      "operatingsystem": "SLES",
+      "operatingsystemrelease": [
+        "15"
+      ]
+    },
+    {
+      "operatingsystem": "Darwin",
+      "operatingsystemrelease": [
+        "16"
+      ]
+    },
+    {
+      "operatingsystem": "Fedora",
+      "operatingsystemrelease": [
+        "29"
+      ]
+    }
+  ],
+  "requirements": [
+    {
+      "name": "puppet",
+      "version_requirement": ">= 5.5.0 < 7.0.0"
+    }
+  ],
+  "pdk-version": "1.13.0",
+  "template-url": "pdk-default#1.13.0",
+  "template-ref": "1.13.0-0-g66e1443"
+}

data/pwshlib.md

@@ -0,0 +1,92 @@
+# 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).