puppet-resource_api 1.8.9 → 1.8.14

data/lib/puppet/resource_api/io_context.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet/resource_api/base_context'
 
 # Implement Resource API Conext to log through an IO object, defaulting to `$stderr`.

data/lib/puppet/resource_api/parameter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet/util'
 require 'puppet/parameter'
 
@@ -13,11 +15,11 @@ class Puppet::ResourceApi::Parameter < Puppet::Parameter
   # @param attribute_name the name of attribue of the parameter
   # @param resource_hash the resource hash instance which is passed to the
   # parent class.
-  def initialize(type_name, data_type, attribute_name, resource_hash)
+  def initialize(type_name, data_type, attribute_name, resource_hash, _referrable_type = nil)
     @type_name = type_name
     @data_type = data_type
     @attribute_name = attribute_name
-    super(resource_hash) # Pass resource to parent Puppet class.
+    super(**resource_hash) # Pass resource to parent Puppet class.
   end
 
   # This method assigns value to the parameter and cleans value.

data/lib/puppet/resource_api/property.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet/util'
 require 'puppet/property'
 
@@ -11,14 +13,31 @@ class Puppet::ResourceApi::Property < Puppet::Property
   # @param attribute_name the name of attribue of the property
   # @param resource_hash the resource hash instance which is passed to the
   # parent class.
-  def initialize(type_name, data_type, attribute_name, resource_hash)
+  def initialize(type_name, data_type, attribute_name, resource_hash, referrable_type = nil)
     @type_name = type_name
     @data_type = data_type
     @attribute_name = attribute_name
-    # Define class method insync?(is) if the name is :ensure
-    def_insync? if @attribute_name == :ensure && self.class != Puppet::ResourceApi::Property
+    @resource = resource_hash[:resource]
+    @referrable_type = referrable_type
+
+    # Do not want to define insync on the base class because
+    # this overrides for everything instead of only for the
+    # appropriate instance/class of the property.
+    if self.class != Puppet::ResourceApi::Property
+      # Define class method insync?(is) if the custom_insync feature flag is set
+      if referrable_type&.type_definition&.feature?('custom_insync')
+        def_custom_insync?
+        if @attribute_name == :rsapi_custom_insync_trigger
+          @change_to_s_value = 'Custom insync logic determined that this resource is out of sync'
+        end
+      # Define class method insync?(is) if the name is :ensure and custom_insync feature flag is not set
+      elsif @attribute_name == :ensure
+        def_ensure_insync?
+      end
+    end
+
     # Pass resource to parent Puppet class.
-    super(resource_hash)
+    super(**resource_hash)
   end
 
   # This method returns value of the property.
@@ -69,10 +88,51 @@ class Puppet::ResourceApi::Property < Puppet::Property
   # method overloaded only for the :ensure property, add option to check if the
   # rs_value matches is. Only if the class is child of
   # Puppet::ResourceApi::Property.
-  def def_insync?
+  def def_ensure_insync?
     define_singleton_method(:insync?) { |is| rs_value.to_s == is.to_s }
   end
 
+  def def_custom_insync?
+    define_singleton_method(:insync?) do |is|
+      provider    = @referrable_type.my_provider
+      context     = @referrable_type.context
+      should_hash = @resource.rsapi_canonicalized_target_state
+      is_hash     = @resource.rsapi_current_state
+      title       = @resource.rsapi_title
+
+      raise(Puppet::DevError, 'No insync? method defined in the provider; an insync? method must be defined if the custom_insync feature is defined for the type') unless provider.respond_to?(:insync?)
+
+      provider_insync_result, change_message = provider.insync?(context, title, @attribute_name, is_hash, should_hash)
+
+      unless provider_insync_result.nil? || change_message.nil? || change_message.empty?
+        @change_to_s_value = change_message
+      end
+
+      case provider_insync_result
+      when nil
+        # If validating ensure and no custom insync was used, check if rs_value matches is.
+        return rs_value.to_s == is.to_s if @attribute_name == :ensure
+        # Otherwise, super and rely on Puppet::Property.insync?
+        super(is)
+      when TrueClass, FalseClass
+        return provider_insync_result
+      else
+        # When returning anything else, raise a DevError for a non-idiomatic return
+        raise(Puppet::DevError, "Custom insync for #{@attribute_name} returned a #{provider_insync_result.class} with a value of #{provider_insync_result.inspect} instead of true/false; insync? MUST return nil or the boolean true or false") # rubocop:disable Metrics/LineLength
+      end
+    end
+
+    define_singleton_method(:change_to_s) do |current_value, newvalue|
+      # As defined in the custom insync? method, it is sometimes useful to overwrite the default change messaging;
+      # The enables a user to return a more useful change report than a strict "is to should" report.
+      # If @change_to_s_value is not set, Puppet writes a generic change notification, like:
+      #   Notice: /Stage[main]/Main/<type_name>[<name_hash>]/<property name>: <property name> changed <is value> to <should value>
+      # If #change_to_s_value is *nil* Puppet writes a weird empty message like:
+      #   Notice: /Stage[main]/Main/<type_name>[<name_hash>]/<property name>:
+      @change_to_s_value || super(current_value, newvalue)
+    end
+  end
+
   # puppet symbolizes some values through puppet/parameter/value.rb
   # (see .convert()), but (especially) Enums are strings. specifying a
   # munge block here skips the value_collection fallback in

data/lib/puppet/resource_api/puppet_context.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet/resource_api/base_context'
 require 'puppet/util/logging'
 

data/lib/puppet/resource_api/read_only_parameter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet/util'
 require 'puppet/resource_api/parameter'
 

data/lib/puppet/resource_api/simple_provider.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Puppet; end # rubocop:disable Style/Documentation
 
 module Puppet::ResourceApi

data/lib/puppet/resource_api/transport.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Puppet::ResourceApi; end # rubocop:disable Style/Documentation
 
 # Remote target transport API

data/lib/puppet/resource_api/transport/wrapper.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet/resource_api/transport'
 require 'hocon'
 require 'hocon/config_syntax'

data/lib/puppet/resource_api/type_definition.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Provides accessor methods for the type being provided
 module Puppet::ResourceApi
   # pre-declare class
@@ -15,7 +17,11 @@ module Puppet::ResourceApi
 
     # rubocop complains when this is named has_feature?
     def feature?(feature)
-      (definition[:features] && definition[:features].include?(feature))
+      definition[:features]&.include?(feature)
+    end
+
+    def title_patterns
+      definition[:title_patterns] ||= []
     end
 
     def validate_schema(definition, attr_key)
@@ -30,10 +36,56 @@ module Puppet::ResourceApi
       Puppet::ResourceApi::DataTypeHandling.validate_ensure(definition)
 
       definition[:features] ||= []
-      supported_features = %w[supports_noop canonicalize remote_resource simple_get_filter].freeze
+      supported_features = %w[supports_noop canonicalize custom_insync remote_resource simple_get_filter].freeze
       unknown_features = definition[:features] - supported_features
       Puppet.warning("Unknown feature detected: #{unknown_features.inspect}") unless unknown_features.empty?
     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.
+    #
+    # type: the Resource API Type the attribute is being created in
+    # attribute_name: the name of the attribute being created
+    # param_or_property: Whether to call the :newparam or :newproperty method
+    # parent: The type of attribute to create: Property, ReadOnly, or Parameter
+    # options: The hash of attribute options, including type, desc, default, and behaviour
+    def create_attribute_in(type, attribute_name, param_or_property, parent, options)
+      type.send(param_or_property, attribute_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(type.name, self.class.data_type, attribute_name, resource_hash, type)
+        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(
+            attribute_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
+    end
   end
 
   # RSAPI Transport schema
@@ -84,6 +136,13 @@ module Puppet::ResourceApi
       }.keys
     end
 
+    def insyncable_attributes
+      @insyncable_attributes ||= attributes.reject { |_name, options|
+        # Only attributes without any behavior are normal Puppet Properties and get insynced
+        options.key?(:behaviour)
+      }.keys
+    end
+
     def validate_schema(definition, attr_key)
       raise Puppet::DevError, '%{type_class} must be a Hash, not `%{other_type}`' % { type_class: self.class.name, other_type: definition.class } unless definition.is_a?(Hash)
       @attributes = definition[attr_key]
@@ -106,6 +165,7 @@ module Puppet::ResourceApi
       Puppet.warning('`%{name}` has no documentation, add it using a `desc` key' % { name: definition[:name] }) unless definition.key? :desc
 
       attributes.each do |key, attr|
+        raise Puppet::DevError, '`rsapi_custom_insync_trigger` cannot be specified as an attribute; it is reserved for propertyless types with the custom_insync feature' if key == :rsapi_custom_insync_trigger # rubocop:disable Metrics/LineLength
         raise Puppet::DevError, "`#{definition[:name]}.#{key}` must be a Hash, not a #{attr.class}" unless attr.is_a? Hash
         raise Puppet::DevError, "`#{definition[:name]}.#{key}` has no type" unless attr.key? :type
         Puppet.warning('`%{name}.%{key}` has no documentation, add it using a `desc` key' % { name: definition[:name], key: key }) unless attr.key? :desc
@@ -190,7 +250,7 @@ module Puppet::ResourceApi
         if is_sensitive
           bad_vals[key] = '<< redacted value >> ' + error_message unless error_message.nil?
         else
-          bad_vals[key] = value unless error_message.nil?
+          bad_vals[key] = "#{value} (#{error_message})" unless error_message.nil?
         end
       end
       bad_vals

data/lib/puppet/resource_api/value_creator.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 responsible for setting default and alias values for the

data/lib/puppet/resource_api/version.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module Puppet
   module ResourceApi
-    VERSION = '1.8.9'.freeze
+    VERSION = '1.8.14'
   end
 end

data/lib/puppet/util/network_device/simple/device.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'hocon'
 require 'hocon/config_syntax'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puppet-resource_api
 version: !ruby/object:Gem::Version
-  version: 1.8.9
+  version: 1.8.14
 platform: ruby
 authors:
 - David Schmitt
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-02-19 00:00:00.000000000 Z
+date: 2021-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hocon
@@ -33,6 +33,7 @@ extra_rdoc_files: []
 files:
 - ".dependency_decisions.yml"
 - ".fixtures.yml"
+- ".github/dependabot.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
@@ -52,6 +53,17 @@ files:
 - codecov.yml
 - contrib/README.md
 - contrib/pre-commit
+- docs/README.md
+- docs/hands-on-lab/01-installing-prereqs.md
+- docs/hands-on-lab/02-connecting-to-the-lightbulbs-emulator.png
+- docs/hands-on-lab/02-connecting-to-the-lightbulbs.md
+- docs/hands-on-lab/03-creating-a-new-module.md
+- docs/hands-on-lab/03-creating-a-new-module_vscode.png
+- docs/hands-on-lab/04-adding-a-new-transport.md
+- docs/hands-on-lab/05-implementing-the-transport-hints.md
+- docs/hands-on-lab/05-implementing-the-transport.md
+- docs/hands-on-lab/06-implementing-the-provider.md
+- docs/hands-on-lab/07-implementing-a-task.md
 - lib/puppet/resource_api.rb
 - lib/puppet/resource_api/base_context.rb
 - lib/puppet/resource_api/data_type_handling.rb
@@ -88,8 +100,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6.2
+rubygems_version: 3.2.5
 signing_key: 
 specification_version: 4
 summary: This library provides a simple way to write new native resources for puppet.