puppet-resource_api 1.8.9 → 1.8.14

data/docs/hands-on-lab/07-implementing-a-task.md

@@ -0,0 +1,181 @@
+# Implementing a Task
+
+> TODO: this is NOT fine, yet
+
+* add bolt gem
+```
+Gemfile:
+  optional:
+    ':development':
+      - gem: 'puppet-resource_api'
+      - gem: 'faraday'
+      # add this
+      - gem: 'bolt'
+```
+
+
+```
+david@davids:~/tmp/hue_workshop$ pdk update --force
+pdk (INFO): Updating david-hue_workshop using the default template, from 1.10.0 to 1.10.0
+
+----------Files to be modified----------
+Gemfile
+
+----------------------------------------
+
+You can find a report of differences in update_report.txt.
+
+
+------------Update completed------------
+
+1 files modified.
+
+david@davids:~/tmp/hue_workshop$ pdk bundle install
+pdk (INFO): Using Ruby 2.5.3
+pdk (INFO): Using Puppet 6.4.2
+[...]
+Bundle complete! 11 Gemfile dependencies, 122 gems now installed.
+Use `bundle info [gemname]` to see where a bundled gem is installed.
+
+david@davids:~/tmp/hue_workshop$
+```
+
+* add ruby_task_helper module
+<!--
+```# .fixtures.yml
+---
+fixtures:
+  forge_modules:
+     ruby_task_helper: "puppetlabs/ruby_task_helper"
+```
+
+```
+david@davids:~/tmp/hue_workshop$ pdk bundle exec rake spec_prep
+pdk (INFO): Using Ruby 2.5.3
+pdk (INFO): Using Puppet 6.4.2
+Notice: Preparing to install into /home/david/tmp/hue_workshop/spec/fixtures/modules ...
+Notice: Downloading from https://forgeapi.puppet.com ...
+Notice: Installing -- do not interrupt ...
+/home/david/tmp/hue_workshop/spec/fixtures/modules
+└── puppetlabs-ruby_task_helper (v0.3.0)
+I, [2019-06-04T13:12:04.615368 #32070]  INFO -- : Creating symlink from spec/fixtures/modules/hue_workshop to /home/david/tmp/hue_workshop
+david@davids:~/tmp/hue_workshop$
+``` -->
+
+Using the development version:
+
+```
+fixtures:
+  # forge_modules:
+  #    ruby_task_helper: "puppetlabs/ruby_task_helper"
+  repositories:
+    ruby_task_helper:
+      repo: "git://github.com/da-ar/puppetlabs-ruby_task_helper"
+      ref: "38745f8e7c2521c50bbf1b8e03318006cdac7a02"
+```
+
+```
+david@davids:~/tmp/hue_workshop$ pdk bundle exec rake spec_prep
+pdk (INFO): Using Ruby 2.5.3
+pdk (INFO): Using Puppet 6.4.2
+HEAD is now at 38745f8 (FM-7955) Update to use Transport helper code
+Cloning into 'spec/fixtures/modules/ruby_task_helper'...
+I, [2019-06-04T13:43:58.577944 #9390]  INFO -- : Creating symlink from spec/fixtures/modules/hue_workshop to /home/david/tmp/hue_workshop
+david@davids:~/tmp/hue_workshop$
+```
+
+* `pdk new task` based on https://github.com/puppetlabs/puppetlabs-panos/blob/main/tasks/apikey.rb
+
+```
+david@davids:~/tmp/hue_workshop$ pdk new task alarm
+pdk (INFO): Creating '/home/david/tmp/hue_workshop/tasks/alarm.sh' from template.
+pdk (INFO): Creating '/home/david/tmp/hue_workshop/tasks/alarm.json' from template.
+david@davids:~/tmp/hue_workshop$ mv /home/david/tmp/hue_workshop/tasks/alarm.sh /home/david/tmp/hue_workshop/tasks/alarm.rb
+david@davids:~/tmp/hue_workshop$
+```
+
+* `tasks/alarm.json`
+```json
+{
+  "puppet_task_version": 1,
+  "supports_noop": false,
+  "remote": true,
+  "description": "A short description of this task",
+  "parameters": {
+    "name": {
+      "type": "String",
+      "description": "The lamp to alarm"
+    }
+  },
+  "files": [
+    "ruby_task_helper/files/task_helper.rb",
+    "hue_workshop/lib/puppet/transport/hue.rb",
+    "hue_workshop/lib/puppet/transport/schema/hue.rb"
+  ]
+}
+```
+
+* `tasks/alarm.rb`
+
+```ruby
+#!/opt/puppetlabs/puppet/bin/ruby
+
+require 'puppet'
+require_relative "../../ruby_task_helper/files/task_helper.rb"
+
+class AlarmTask < TaskHelper
+  def task(params = {}, remote = nil)
+    name = params[:name]
+    5.times do |i|
+      remote.transport.hue_put("lights/#{name}/state",
+        name: name,
+        on: false,
+      )
+      sleep 1.0
+      remote.transport.hue_put("lights/#{name}/state",
+        name: name,
+        on: true,
+        hue: 10000*i,
+        sat: 255
+      )
+      sleep 1.0
+    end
+    {}
+  end
+end
+
+if __FILE__ == $0
+  AlarmTask.run
+end
+```
+
+* execute `pdk bundle exec bolt ...`
+
+```yaml
+# inventory.yaml
+---
+nodes:
+  - name: "192.168.43.195"
+    alias: hub1
+    config:
+      transport: remote
+      remote:
+        remote-transport: hue
+        key: "onmdTvd198bMrC6QYyVE9iasfYSeyAbAj3XyQzfL"
+```
+
+```
+david@davids:~/tmp/hue_workshop$ pdk bundle exec bolt task run hue_workshop::alarm --modulepath spec/fixtures/modules/ --target hub1 --inventoryfile inventory.yaml
+pdk (INFO): Using Ruby 2.5.3
+pdk (INFO): Using Puppet 6.4.2
+Started on 192.168.43.195...
+Finished on 192.168.43.195:
+  {
+  }
+Successful on 1 node: 192.168.43.195
+Ran on 1 node in 11.32 seconds
+
+david@davids:~/tmp/hue_workshop$
+```
+
+* profit!

data/lib/puppet/resource_api.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'pathname'
 require 'puppet/resource_api/data_type_handling'
 require 'puppet/resource_api/glue'
@@ -35,7 +37,8 @@ module Puppet::ResourceApi
     end
 
     Puppet::Type.newtype(definition[:name].to_sym) do
-      @docs = definition[:desc]
+      # The :desc value is already cleaned up by the TypeDefinition validation
+      @doc = definition[:desc]
       @type_definition = type_def
 
       # Keeps a copy of the provider around. Weird naming to avoid clashes with puppet's own `provider` member
@@ -122,6 +125,22 @@ module Puppet::ResourceApi
         @rsapi_title
       end
 
+      def rsapi_canonicalized_target_state
+        @rsapi_canonicalized_target_state ||= begin
+          # skip puppet's injected metaparams
+          actual_params = @parameters.select { |k, _v| type_definition.attributes.key? k }
+          target_state = Hash[actual_params.map { |k, v| [k, v.rs_value] }]
+          target_state = my_provider.canonicalize(context, [target_state]).first if type_definition.feature?('canonicalize')
+          target_state
+        end
+        @rsapi_canonicalized_target_state
+      end
+
+      def rsapi_current_state
+        refresh_current_state unless @rsapi_current_state
+        @rsapi_current_state
+      end
+
       def to_resource
         to_resource_shim(super)
       end
@@ -165,6 +184,21 @@ module Puppet::ResourceApi
         raise_missing_params if @missing_params.any?
       end
 
+      # If the custom_insync feature is specified but no insyncable attributes are included
+      # in the definition, add the hidden rsapi_custom_insync_trigger property.
+      # This property exists *only* to allow a resource without properties to still execute an
+      # insync check; there's no point in specifying it in a manifest as it can only have one
+      # value; it cannot be specified in a type definition as it should only exist in this case.
+      if type_definition.feature?('custom_insync') && type_definition.insyncable_attributes.empty?
+        custom_insync_trigger_options = {
+          type: 'Enum[do_not_specify_in_manifest]',
+          desc: 'A hidden property which enables a type with custom insync to perform an insync check without specifying any insyncable properties',
+          default: 'do_not_specify_in_manifest',
+        }
+
+        type_definition.create_attribute_in(self, :rsapi_custom_insync_trigger, :newproperty, Puppet::ResourceApi::Property, custom_insync_trigger_options)
+      end
+
       definition[:attributes].each do |name, options|
         # puts "#{name}: #{options.inspect}"
 
@@ -188,43 +222,7 @@ module Puppet::ResourceApi
           parent = Puppet::ResourceApi::Property
         end
 
-        # This call creates a new parameter or property with all work-arounds or
-        # customizations required by the Resource API applied. Under the hood,
-        # this maps to the relevant DSL methods in Puppet::Type. See
-        # https://puppet.com/docs/puppet/6.0/custom_types.html#reference-5883
-        # for details.
-        send(param_or_property, name.to_sym, parent: parent) do
-          if options[:desc]
-            desc "#{options[:desc]} (a #{options[:type]})"
-          end
-
-          # The initialize method is called when puppet core starts building up
-          # type objects. The core passes in a hash of shape { resource:
-          # #<Puppet::Type::TypeName> }. We use this to pass through the
-          # required configuration data to the parent (see
-          # Puppet::ResourceApi::Property, Puppet::ResourceApi::Parameter and
-          # Puppet::ResourceApi::ReadOnlyParameter).
-          define_method(:initialize) do |resource_hash|
-            super(definition[:name], self.class.data_type, name, resource_hash)
-          end
-
-          # get pops data type object for this parameter or property
-          define_singleton_method(:data_type) do
-            @rsapi_data_type ||= Puppet::ResourceApi::DataTypeHandling.parse_puppet_type(
-              name,
-              options[:type],
-            )
-          end
-
-          # from ValueCreator call create_values which makes alias values and
-          # default values for properties and params
-          Puppet::ResourceApi::ValueCreator.create_values(
-            self,
-            data_type,
-            param_or_property,
-            options,
-          )
-        end
+        type_definition.create_attribute_in(self, name, param_or_property, parent, options)
       end
 
       def self.instances
@@ -260,7 +258,7 @@ module Puppet::ResourceApi
 
         if @rsapi_current_state
           type_definition.check_schema(@rsapi_current_state)
-          strict_check(@rsapi_current_state) if type_definition.feature?('canonicalize')
+          strict_check(@rsapi_current_state)
         else
           @rsapi_current_state = if rsapi_title.is_a? Hash
                                    rsapi_title.dup
@@ -274,15 +272,13 @@ module Puppet::ResourceApi
       # Use this to set the current state from the `instances` method
       def cache_current_state(resource_hash)
         @rsapi_current_state = resource_hash
-        strict_check(@rsapi_current_state) if type_definition.feature?('canonicalize')
+        strict_check(@rsapi_current_state)
       end
 
       def retrieve
-        refresh_current_state unless @rsapi_current_state
-
-        Puppet.debug("Current State: #{@rsapi_current_state.inspect}")
+        Puppet.debug("Current State: #{rsapi_current_state.inspect}")
 
-        result = Puppet::Resource.new(self.class, title, parameters: @rsapi_current_state)
+        result = Puppet::Resource.new(self.class, title, parameters: rsapi_current_state)
         # puppet needs ensure to be a symbol
         result[:ensure] = result[:ensure].to_sym if type_definition.ensurable? && result[:ensure].is_a?(String)
 
@@ -301,10 +297,7 @@ module Puppet::ResourceApi
         raise_missing_attrs
 
         # puts 'flush'
-        # skip puppet's injected metaparams
-        actual_params = @parameters.select { |k, _v| type_definition.attributes.key? k }
-        target_state = Hash[actual_params.map { |k, v| [k, v.rs_value] }]
-        target_state = my_provider.canonicalize(context, [target_state]).first if type_definition.feature?('canonicalize')
+        target_state = rsapi_canonicalized_target_state
 
         retrieve unless @rsapi_current_state
 
@@ -331,7 +324,10 @@ module Puppet::ResourceApi
         else
           my_provider.set(context, rsapi_title => { is: @rsapi_current_state, should: target_state }) unless noop?
         end
-        raise 'Execution encountered an error' if context.failed?
+        if context.failed?
+          context.reset_failed
+          raise 'Execution encountered an error'
+        end
 
         # remember that we have successfully reached our desired state
         @rsapi_current_state = target_state
@@ -350,6 +346,22 @@ module Puppet::ResourceApi
       def strict_check(current_state)
         return if Puppet.settings[:strict] == :off
 
+        strict_check_canonicalize(current_state) if type_definition.feature?('canonicalize')
+        strict_check_title_parameter(current_state) if type_definition.namevars.size > 1 && !type_definition.title_patterns.empty?
+
+        nil
+      end
+
+      def strict_message(message)
+        case Puppet.settings[:strict]
+        when :warning
+          Puppet.warning(message)
+        when :error
+          raise Puppet::DevError, message
+        end
+      end
+
+      def strict_check_canonicalize(current_state)
         # if strict checking is on we must notify if the values are changed by canonicalize
         # make a deep copy to perform the operation on and to compare against later
         state_clone = Marshal.load(Marshal.dump(current_state))
@@ -366,15 +378,43 @@ Returned values:       #{current_state.inspect}
 Canonicalized values:  #{state_clone.inspect}
 MESSAGE
         #:nocov:
+        strict_message(message)
+      end
 
-        case Puppet.settings[:strict]
-        when :warning
-          Puppet.warning(message)
-        when :error
-          raise Puppet::DevError, message
+      def strict_check_title_parameter(current_state)
+        unless current_state.key?(:title)
+          strict_message("#{type_definition.name}[#{@title}]#get has not provided a title attribute.")
+          return
         end
 
-        nil
+        # Logic borrowed from Puppet::Resource.parse_title
+        title_hash = {}
+        self.class.title_patterns.each do |regexp, symbols|
+          captures = regexp.match(current_state[:title])
+          next if captures.nil?
+          symbols.zip(captures[1..-1]).each do |symbol_and_lambda, capture|
+            # The Resource API does not support passing procs in title_patterns
+            # so, unlike Puppet::Resource, we do not need to handle that here.
+            symbol = symbol_and_lambda[0]
+            title_hash[symbol] = capture
+          end
+          break
+        end
+
+        return if title_hash == rsapi_title
+
+        namevars = type_definition.namevars.reject { |namevar| title_hash[namevar] == rsapi_title[namevar] }
+
+        #:nocov:
+        # codecov fails to register this multiline as covered, even though simplecov does.
+        message = <<MESSAGE.strip
+#{type_definition.name}[#{@title}]#get has provided a title attribute which does not match all namevars.
+Namevars which do not match: #{namevars.inspect}
+Returned parsed title hash:  #{title_hash.inspect}
+Expected hash:               #{rsapi_title.inspect}
+MESSAGE
+        #:nocov:
+        strict_message(message)
       end
 
       define_singleton_method(:context) do

data/lib/puppet/resource_api/base_context.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet/resource_api/type_definition'
 
 # rubocop:disable Style/Documentation
@@ -33,6 +35,10 @@ class Puppet::ResourceApi::BaseContext
     @failed
   end
 
+  def reset_failed
+    @failed = false
+  end
+
   def feature_support?(feature)
     Puppet.deprecation_warning('context.feature_support? is deprecated. Please use context.type.feature? instead.')
     type.feature?(feature)

data/lib/puppet/resource_api/data_type_handling.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Puppet; module ResourceApi; end; end # predeclare the main module # rubocop:disable Style/Documentation,Style/ClassAndModuleChildren
 
 # This module is used to handle data inside types, contains methods for munging

data/lib/puppet/resource_api/glue.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'yaml'
 
 module Puppet; end # rubocop:disable Style/Documentation
@@ -35,6 +37,11 @@ module Puppet::ResourceApi
       end + ['}']).compact.join("\n")
     end
 
+    # Required to enable `puppet device --resource ... --to_yaml` workflow
+    def to_hiera_hash
+      to_hierayaml
+    end
+
     # Convert our resource to yaml for Hiera purposes.
     def to_hierayaml
       attributes = Hash[filtered_keys.map { |k| [k.to_s, values[k]] }]
@@ -52,9 +59,9 @@ module Puppet::ResourceApi
       values
     end
 
-    # attribute names that are not title or namevars
+    # attribute names that are not title, namevars, or rsapi_custom_insync_trigger
     def filtered_keys
-      values.keys.reject { |k| k == :title || !attr_def[k] || (attr_def[k][:behaviour] == :namevar && @namevars.size == 1) }
+      values.keys.reject { |k| k == :title || k == :rsapi_custom_insync_trigger || !attr_def[k] || (attr_def[k][:behaviour] == :namevar && @namevars.size == 1) }
     end
   end